@ampcode/plugin

Amp Plugin API

Amp plugins are TypeScript files that extend and customize Amp. Plugins live in .amp/plugins/ (project) or ~/.config/amp/plugins/ (global).

The Amp plugin API is experimental. Expect many breaking changes if you choose to use it right now. Do not use it for anything critical.

The plugin API supports:

• Event handlers — amp.on(...) for hooking into tool calls, messages, and other events
• Tools — amp.registerTool(...) for custom tools
• Commands — amp.registerCommand(...) to add to Amp's command palette
• User input and UI — ctx.ui.notify(...), ctx.ui.confirm(...)
• AI & system utilities — amp.ai.ask(...) for yes-no LLM answers

You can use plugins to:

• Format files and report file diagnostics after each edit
• Ensure Amp runs tests before finishing its work
• Block or require confirmation for commands you deem risky
• Correct common agent mistakes that AGENTS.md alone can't fix

See Amp Plugin API documentation.

Using Plugins

Run the Amp CLI with PLUGINS=all amp to use plugins. If the PLUGINS env var is not set, plugins are disabled. Plugins can execute arbitrary code, so only enable plugins when running Amp in trusted workspaces.

Limitations:

• The Amp plugin API only works in the Amp CLI, not the Amp editor extension.
• The Amp plugin API only works when the Amp CLI is installed via the binary install method, not via npm install.

Authoring Plugins

Use this prompt:

Make an Amp plugin to __________. See https://ampcode.com/manual/plugin-api for docs.

• Ensure you're running with PLUGINS=all amp
• Use Ctrl-o plugins: reload to reload all plugins after they're changed.
• All plugin files must start with // @i-know-the-amp-plugin-api-is-wip-and-very-experimental-right-now.

Example Plugin

.amp/plugins/permissions.ts:

// @i-know-the-amp-plugin-api-is-wip-and-very-experimental-right-now
import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	// Ask the user before executing any tool.
	amp.on('tool.call', async (event, ctx) => {
		const confirmed = await ctx.ui.confirm({
			title: `Allow ${event.tool}?`,
			message: `The agent wants to execute the "${event.tool}" tool.`,
			confirmButtonText: 'Allow',
		})
		if (!confirmed) {
			ctx.logger.log(`User rejected tool execution: ${event.tool}`)
			return {
				action: 'reject-and-continue',
				message: `User rejected execution of tool ${event.tool}.`,
			}
		}
		return { action: 'allow' }
	})
}

Acknowledgment

Amp's plugin API is inspired by pi's extension API, created by the awesome genius Mario Zechner.