Amp Plugin API

Amp plugins are TypeScript files that extend and customize Amp.

Plugins can:

• Handle events — amp.on(...) for tool calls, tool results, and agent lifecycle events
• Add tools — amp.registerTool(...) for custom tools the agent can call
• Add commands — amp.registerCommand(...) for command palette actions
• Show UI — ctx.ui.notify(...), ctx.ui.confirm(...), ctx.ui.input(...), and ctx.ui.select(...)
• Classify with AI — amp.ai.ask(...) for yes/no decisions with confidence and reasoning

Locations

Amp loads plugins from three locations:

• Project plugins — .amp/plugins/*.ts
• System plugins — ~/.config/amp/plugins/*.ts
• Global plugins — configured in workspace settings (limited experimental release)

Minimal Plugin

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.logger.log('Plugin initialized')

	amp.on('session.start', async (event, ctx) => {
		await ctx.ui.notify(`Thread ${event.thread.id} started.`)
	})
}

Code in the exported function runs when the plugin loads. Use session.start only for work that should run when Amp starts a specific thread session.

After changing a plugin, open the command palette and run plugins: reload.

Documentation

• Plugin guide and worked examples: https://ampcode.com/manual#plugins
• Full @ampcode/plugin type reference and a complete kitchen-sink example: https://ampcode.com/manual/plugin-api

Plugins execute code, so only use plugins from people and workspaces you trust.

Acknowledgment

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