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
• Bundle skills — await amp.registerSkill(...) to register skill directories
• Add commands — amp.registerCommand(...) for command palette actions
• Show UI — ctx.ui.notify(...), ctx.ui.confirm(...), ctx.ui.input(...), and ctx.ui.select(...)
• Use AI — amp.ai.ask(...) for thread-scoped yes/no classification that defaults to no reasoning unless { reasoningEffort } is set
• Decide fast — amp.ai.decide(...), amp.ai.choice(...), amp.ai.noul(...), and amp.ai.score(...) for typed decisions with calibrated probabilities and no generated text, answered by TypeSafe's Jev, or by OpenAI's Decisions API when you pass { model: 'openai/gpt-6-luna' }
• Label threads — ctx.thread.labels(), ctx.thread.addLabels(...), and ctx.thread.setLabels(...) to read and change the current thread's labels
• Upload attachments — amp.attachments.upload(...) to upload image bytes and get back a URL for URL-backed { type: 'image', mimeType, url } tool result blocks, keeping large images out of thread state

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 const description = 'Shows a notification when a thread session starts'

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.`)
    })
}

The optional description named export must be a static string literal of at most 300 characters. Amp shows it in plugin settings and ignores missing, dynamic, or longer values.

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, or restart Amp.

Documentation

• Plugin guide and worked examples: https://ampcode.com/docs/customize/plugins
• Full @ampcode/plugin type reference and a complete kitchen-sink example: https://ampcode.com/docs/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.