Amp Owner’s Manual

Congratulations on installing Amp. This manual helps you get the most out of it.

Why Amp?

Amp is the frontier coding agent for your terminal and editor.

• Multi-Model: Opus 4.7, GPT-5.4, fast models—Amp uses them all, for what each model is best at.
• Opinionated: You’re always using the good parts of Amp. If we don’t use and love a feature, we kill it.
• On the Frontier: Amp goes where the models take it. No backcompat, no legacy features.
• Threads: You can save and share your interactions with Amp. You wouldn’t code without version control, would you?

Amp has 3 modes: smart (unconstrained state-of-the-art model use), rush (faster, cheaper, suited for small, well-defined tasks), and deep (deep reasoning with extended thinking for complex problems).

Want to go much deeper? Follow along on our Raising an Agent podcast where we share what we’re learning as we build Amp, and see our FIF.

Get Started

1. Sign into ampcode.com/install.
2. Follow the instructions to install the Amp CLI.

You’re ready to start using Amp!

Command Line

Our recommended install method for macOS, Linux and WSL. It supports auto-updating and fast launch via Bun.

On Windows, we recommend running Amp in WSL using WezTerm or Alacritty instead of Windows Terminal, for fully functional clipboard support.

Install the Amp CLI:

curl -fsSL https://ampcode.com/install.sh | bash

Run interactively (will prompt for login on first run):

amp

You can also install via npm if necessary.

IDE integrations

Sign into ampcode.com/install and follow the instructions, or:

• JetBrains (IntelliJ, WebStorm, GoLand, etc.): Install the Amp CLI, then run amp --jetbrains.
• Neovim: Install the Amp CLI and the Amp Neovim plugin, then run amp.
• VS Code and VS Code-based editors (Cursor, Windsurf, etc.): Install the Amp CLI, ensure your editor is running, then run amp.
• Zed: Install the Amp CLI, ensure Zed is running, then run amp.

Connect Amp to an IDE by opening the command palette (Ctrl+O) and selecting ide connect.

Using Amp

Agent Modes

Amp has 3 modes:

• smart: Uses state-of-the-art models without constraints for maximum capability and autonomy.
• rush: Faster, cheaper, and less capable, suitable for small, well-defined tasks. See Rush Mode.
• deep: Deep reasoning with GPT-5.5 for extended thinking on complex problems.

There’s one more that’s hidden: large mode.

See Models for the models used by each mode.

Switch modes in the CLI by opening the command palette (Ctrl+O) and typing mode.

How to Prompt

Amp’s smart mode currently uses Claude Opus 4.7, with up to 300k input context tokens. For the best results, follow these guidelines:

• Be explicit with what you want. Instead of “can you do X?”, try “do X.”
• Keep it short, keep it focused. Break very large tasks up into smaller sub-tasks, one per thread. Do not ask the agent to write database migrations in the same thread as it previously changed CSS for a documentation page.
• Don’t try to make the model guess. If you know something about how to achieve what you want the agent to do — which files to look at, which commands to run — put it in your prompt.
• If you want the model to not write any code, but only to research and plan, say so: “Only plan how to implement this. Do NOT write any code.”
• Use AGENTS.md files to guide Amp on how to run your tests and build steps and to avoid common mistakes.
• Abandon threads if they accumulated too much noise. Sometimes things go wrong and failed attempts with error messages clutter up the context window. In those cases, it’s often best to start with a new thread and a clean context window.
• Tell the agent how to best review its work: what command or test to run, what URL to open, which logs to read. Feedback helps agents as much as it helps us.

The first prompt in the thread carries a lot of weight. It sets the direction for the rest of the conversation. We encourage you to be deliberate with it. In the Amp CLI, Enter submits, and you can use Shift+Enter (with terminal support) or Ctrl+J to insert a newline.

Here are some examples of prompts we’ve used with Amp:

• “Make observeThreadGuidanceFiles return Omit<ResolvedGuidanceFile, 'content'>[] and remove that field from its return value, and update the tests. Note that it is omitted because this is used in places that do not need the file contents, and this saves on data transferred over the view API.” (See Thread)
• “Run <build command> and fix all the errors”
• “Look at <local development server url> to see this UI component. Then change it so that it looks more minimal. Frequently check your work by screenshotting the URL”
• “Run git blame on the file I have open and figure out who added that new title”
• “Convert these 5 files to use Tailwind, use one subagent per file”
• “Take a look at git diff — someone helped me build a debug tool to edit a Thread directly in JSON. Please analyze the code and see how it works and how it can be improved. […]” (See Thread)
• “Check git diff --staged and remove the debug statements someone added” (See Thread)
• “Find the commit that added this using git log, look at the whole commit, then help me change this feature”
• “Explain the relationship between class AutoScroller and ViewUpdater using a diagram”
• “Run psql and rewire all the threads in the databaser to my user (email starts with thorsten)” (See Thread)

Also see Thorsten Ball’s How I Use Amp.

If you’re in a workspace, use Amp’s thread sharing to learn from each other.

AGENTS.md

Amp looks in AGENTS.md files for guidance on codebase structure, build/test commands, and conventions.

Amp includes AGENTS.md files automatically:

• AGENTS.md files in the current working directory (or editor workspace roots) and parent directories (up to $HOME) are always included.
• Subtree AGENTS.md files are included when the agent reads a file in the subtree.
• System-wide guidance files, as well as both $HOME/.config/amp/AGENTS.md and $HOME/.config/AGENTS.md, are always included if they exist.

If no AGENTS.md exists in a directory, but a file named AGENT.md (without an S) or CLAUDE.md does exist, that file will be included.

In a large repository with multiple subprojects, we recommend keeping the top-level AGENTS.md general and creating more specific AGENTS.md files in subtrees for each subproject.

To see the agent files that Amp is using, select agents-md list from the command palette.

Writing AGENTS.md Files

Amp offers to generate an AGENTS.md file for you if none exists. You can create or update any AGENTS.md files manually or by asking Amp (“Update AGENTS.md based on what I told you in this thread”).

To include other files as context, @-mention them in agent files. For example:

See @doc/style.md and @specs/**/*.md.

When making commits, see @doc/git-commit-instructions.md.

• Relative paths are interpreted relative to the agent file containing the mention.
• Absolute paths and @~/some/path are also supported.
• @-mentions in code blocks are ignored, to avoid false positives.
• Glob patterns are supported (such as @doc/*.md or @.agent/**/*.md).

Granular Guidance

To provide guidance that only applies when working with certain files, you can specify globs in YAML front matter of mentioned files.

For example, to apply language-specific coding rules:

1. Put See @docs/*.md anywhere in your AGENTS.md file.

2. Create a file docs/typescript-conventions.md with:

   ---
   globs:
     - '**/*.ts'
     - '**/*.tsx'
   ---
   
   Follow these TypeScript conventions:
   
   - Never use the `any` type
   - ...

3. Repeat for other languages.

Mentioned files with globs will only be included if Amp has read a file matching any of the globs (in the example above, any TypeScript file). If no globs are specified, the file is always included when @-mentioned.

Globs are implicitly prefixed with **/ unless they start with ../ or ./, in which case they refer to paths relative to the mentioned file.

Other examples:

• Frontend-specific guidance: globs: ["src/components/**", "**/*.tsx"]
• Backend guidance: globs: ["server/**", "api/**"]
• Test guidance: globs: ["*.test.ts", "__tests__/*"]

Referencing Other Threads

You can reference other Amp threads by thread URL (e.g., https://ampcode.com/threads/T-7f395a45-7fae-4983-8de0-d02e61d30183) or thread ID (e.g., @T-7f395a45-7fae-4983-8de0-d02e61d30183) in your prompt.

Type @@ to search for a thread to mention.

For each mentioned thread, Amp will read and extract relevant information to your current task. This is useful to continue work from or reuse techniques from a previous thread.

Examples:

• Implement the plan from https://ampcode.com/threads/T-7f395a45-7fae-4983-8de0-d02e61d30183
• Apply the same fix from @T-7f395a45-7fae-4983-8de0-d02e61d30183 to the form here

Finding Threads

Amp can search through your past threads and your workspace members’ threads to find relevant conversations. Ask Amp to find threads by keyword, file path, repository, author, date, or task.

Examples:

• Find threads where we discussed the monorepo migration
• Show me threads that modified src/server/index.ts
• Find Thorsten's threads on the indexing logic
• Show me my recent threads from the last week
• Which threads worked on task 142?
• Find threads related to this one

Archiving Threads

When you archive a thread, it no longer appears in your list of active threads but can still be viewed on the web and referenced by @-mention.

To archive a thread, from the command palette, run thread: archive and exit in the CLI.

Attaching Images

You can attach images (such as screenshots and diagrams) to your messages.

In the CLI, press Ctrl+V to paste an image from the clipboard. Note that you must use Ctrl+V, not Cmd+V, even on macOS. On Windows, if Ctrl+V does not work, press Ctrl+O and run paste image from clipboard in the Amp command palette.

On Windows, image pasting is more reliable in WezTerm or Alacritty than in Windows Terminal.

You can also @-mention images by file path.

Mentioning Files

Type @ to search for a file to mention.

Edit

To edit a prior message in the CLI, press Tab to navigate to prior messages, then press e.

Queueing Messages

You can queue messages to be sent to the agent once it ends its turn, without interrupting its current work. In the CLI, first draft your next prompt, then open the command palette and run queue.

Amp runs tools and shell commands on your behalf to inspect code, run tests, and iterate quickly.

By default, Amp does not ask for approval before running tools.

Amp acts on content in your workspace. Untrusted repositories, MCP servers, and other external inputs can influence what Amp does. If you regularly work with untrusted sources, consider creating a custom policy plugin, or using an isolated development environment.

Built-in Tools

You can see Amp’s builtin tools by running amp tools list in the CLI.

Toolboxes

Toolboxes allow you to extend Amp with simple scripts instead of needing to provide an MCP server.

When Amp starts it invokes each executable in the directory indicated by AMP_TOOLBOX, with the environment variable TOOLBOX_ACTION set to describe.

The tool is expected to write its description to stdout as a list of key-value pairs, one per line.

#!/usr/bin/env bun

const action = process.env.TOOLBOX_ACTION

if (action === 'describe') showDescription()
else if (action === 'execute') runTests()

function showDescription() {
	process.stdout.write(
		[
			'name: run-tests',
			'description: use this tool instead of Bash to run tests in a workspace',
			'dir: string the workspace directory',
		].join('\n'),
	)
}

When Amp decides to use your tool it runs the executable again, setting TOOLBOX_ACTION to execute.

The tool receives parameters in the same format on stdin and then performs its work:

function runTests() {
	let dir = require('fs')
		.readFileSync(0, 'utf-8')
		.split('\n')
		.filter((line) => line.startsWith('dir: '))

	dir = dir.length > 0 ? dir[0].replace('dir: ', '') : '.'

	require('child_process').spawnSync('pnpm', ['-C', dir, 'run', 'test', '--no-color', '--run'], {
		stdio: 'inherit',
	})
}

If your tool needs object or array parameters, the executable can write its tool schema as JSON instead to stdout. In this case it’ll also receive inputs as JSON.

We recommend using tools to express specific, deterministic and project-local behavior, like:

• querying a development database,
• running test and build actions in the project,
• exposing CLIs tools in a controlled manner.

See the Appendix for the full technical reference.

Agent Skills

Skills are packages of instructions and resources that teach the agent how to perform specific tasks. Amp includes built-in skills, and you can install or create your own—either project-specific (.agents/skills/) or user-wide (~/.config/agents/skills/).

Creating Skills

Amp has a built-in building-skills skill that can create skills tailored to your codebase, workflow, and systems. To create one, just ask:

Create a skill for deploying to staging

Ask for a “project-specific skill” to save it to the current project, or a “user-wide skill” for personal use across all your projects. Project skills live in .agents/skills/ and can be committed to git so your team gets them automatically.

Skill precedence (first wins):

• ~/.config/agents/skills/
• ~/.config/amp/skills/
• .agents/skills/
• .claude/skills/
• ~/.claude/skills/
• Plugins, toolbox directories, and built-in skills

Viewing Skills

To view installed skills, use the command palette (Ctrl+O in the CLI):

• skill: list — View installed skills

Skill Format

Each skill is a directory containing a SKILL.md file with YAML frontmatter:

---
name: my-skill
description: A description of what this skill does
---

# My Skill Instructions

Detailed instructions for the agent...

The name and description are always visible to the model and determine when it invokes the skill. Names must be unique—project-specific skills take priority over user-wide, and both override built-in skills. The rest of the SKILL.md content is only loaded on demand when the skill is invoked.

Skills can include bundled resources (scripts, templates, etc.) in the same directory, which the agent can access relative to the skill file.

MCP Servers in Skills

Skills can bundle MCP servers by including an mcp.json file in the skill directory. The servers start when Amp launches, but their tools remain hidden until the skill is loaded. This is the recommended way to use MCP servers—it keeps the tool list clean and reduces context bloat compared to adding servers directly to your Amp configuration.

Example mcp.json (local command-based server):

{
	"chrome-devtools": {
		"command": "npx",
		"args": ["-y", "chrome-devtools-mcp@latest"],
		"includeTools": ["navigate_*", "take_screenshot", "click", "fill*"]
	}
}

Example mcp.json (remote HTTP server):

{
	"linear": {
		"url": "https://mcp.linear.app/sse",
		"includeTools": ["list_issues", "create_issue", "update_issue"]
	}
}

Fields for local servers:

• command (string) — the command to run
• args (string[], optional) — command arguments
• env (object, optional) — environment variables

Fields for remote servers:

• url (string) — the server endpoint
• headers (object, optional) — HTTP headers to send with requests

Common fields:

• includeTools (string[], optional but recommended) — tool names or glob patterns to filter which tools are exposed

Subagents

Amp can spawn subagents (via the Task tool) for complex tasks that benefit from independent execution. Each subagent has its own context window and access to tools like file editing and terminal commands.

Subagents are most useful for multi-step tasks that can be broken into independent parts, operations producing extensive output not needed after completion, parallel work across different code areas, and keeping the main thread’s context clean while coordinating complex work.

However, subagents work in isolation — they can’t communicate with each other, you can’t guide them mid-task, they start fresh without your conversation’s accumulated context, and the main agent only receives their final summary rather than monitoring their step-by-step work.

Amp may use subagents automatically for suitable tasks, or you can encourage their use by mentioning subagents or suggesting parallel work.

Oracle

Amp has access to a powerful “second opinion” model that’s better suited for complex reasoning or analysis tasks, at the cost of being slightly slower, slightly more expensive, and less suited to day-to-day code editing tasks than the main agent’s model.

This model is available to Amp’s main agent through a tool called oracle, and it currently uses GPT-5.4, with reasoning level high.

The main agent can autonomously decide to ask the oracle for help when debugging or reviewing a complex piece of code. We intentionally do not force the main agent to always use the oracle, due to higher costs and slower inference speed.

We recommend explicitly asking Amp’s main agent to use the oracle when you think it will be helpful. Here are some examples from our own usage of Amp:

• “Use the oracle to review the last commit’s changes. I want to make sure that the actual logic for when an idle or requires-user-input notification sound plays has not changed.”
• “Ask the oracle whether there isn’t a better solution.”
• “I have a bug in these files: … It shows up when I run this command: … Help me fix this bug. Use the oracle as much as possible, since it’s smart.”
• “Analyze how the functions foobar and barfoo are used. Then I want you to work a lot with the oracle to figure out how we can refactor the duplication between them while keeping changes backwards compatible.”

See the GPT-5 oracle announcement for more information.

Librarian

Amp can search remote codebases with the use of the Librarian subagent. The Librarian can search and read all public code on GitHub as well as your private GitHub repositories.

Tell Amp to summon the Librarian when you need to do cross-repository research, or, for example, when you want it to read the code of the frameworks and libraries you’re using. The Librarian’s answers are typically longer and more detailed as we built it to provide in-depth explanations. The Librarian will only search code on the default branch of the repository.

You might need to prompt the main agent explicitly to use the Librarian. Here are some examples:

• “Explain how new versions of our documentation are deployed when we release. Search our docs and infra repositories to see how they get to X.Y.sourcegraph.com.”
• “I have a bug in this validation code using Zod, it’s throwing a weird error. Ask the Librarian to investigate why the error is happening and show me the logic causing it.”
• “Use the Librarian to investigate the foo service - were there any recent changes to the API endpoints I am using in bar? If so, what are they and when were they merged?”

See the Librarian announcement for more information.

GitHub

You need to configure a connection to GitHub in your settings to use it. If you want the Librarian to be able to see your private repositories, you need to select them when configuring your GitHub connection. See GitHub’s documentation on installing and authorizing GitHub apps for more information.

Bitbucket Enterprise

The Librarian can also search and read code on Bitbucket Enterprise (Bitbucket Data Center / Server) instances. Setup requires two steps:

1. Workspace admin: Add your Bitbucket Enterprise instance URL via the workspace connections page (Workspace Settings → Connections).
2. Each user: Add your personal access token to your configuration file:

"amp.bitbucketToken": "YOUR_PERSONAL_ACCESS_TOKEN"

To create a Personal Access Token, go to your Bitbucket Enterprise instance → Account → HTTP access tokens → Create a token with Repository read permissions.

Painter

Amp can generate and edit images using the Painter tool, powered by Gemini 3 Pro Image.

Tell Amp to use the Painter when you need to create UI mockups, app icons, hero images, or edit existing images such as redacting sensitive information from screenshots. You can also provide up to 3 reference images for style guidance or editing by @-mentioning image files in your prompt.

You might need to prompt the Amp explicitly to use the Painter. Here are some examples:

• “Use the painter to create a UI mockup for my settings page.”
• “Use the painter to generate an app icon for my CLI tool. Dark background with a glowing terminal cursor in cyan.”
• “Use the painter to redact any visible API keys or passwords in this terminal screenshot.”

See the Painter announcement for more information.

Code Review

Amp can review your code for bugs, security issues, performance problems, and style violations—run amp review in the CLI or simply ask the main agent to review your changes.

Checks

Checks are user-defined review criteria scoped to specific parts of your codebase. They let you codify team conventions, security invariants, and best practices that linters don’t catch. During code review, Amp spawns a separate subagent for each check.

Create Markdown files in .agents/checks/ directories with YAML frontmatter:

Example (.agents/checks/perf.md):

---
name: performance
description: Flags common performance anti-patterns
severity-default: medium
tools: [Grep, Read]
---

Look for these patterns:

- Nested loops over the same collection (O(n²) → O(n) with a Set/Map)
- Repeated `array.includes()` in a loop
- Sorting inside a loop
- String concatenation in a loop (use array + join)

Report the line, why it matters, and how to fix it.

Checks can be defined in project and global locations:

• .agents/checks/ — applies to entire codebase
• api/.agents/checks/ — applies only to files under api/
• $HOME/.config/amp/checks/ or $HOME/.config/agents/checks/ — global checks applied to all reviews

Closer project checks override same-named checks from parent directories and global checks.

MCP

You can add additional tools using MCP (Model Context Protocol) servers, which can be either local or remote.

For most use cases, we recommend bundling MCP servers in skills via mcp.json instead of adding them to your user settings. This keeps the tool list clean and loads MCP tools only when needed.

If loading the MCP via skills isn’t suitable (if it must be always available in the context window), add it via the CLI or in your configuration file:

$ amp mcp add context7 -- npx -y @upstash/context7-mcp
$ amp mcp add linear https://mcp.linear.app/sse

MCP servers use the same configuration fields as MCP servers in skills—command/args/env for local servers, url/headers for remote. In configuration files, set amp.mcpServers and use ${VAR_NAME} syntax for environment variables:

"amp.mcpServers": {
    "playwright": {
        "command": "npx",
        "args": ["-y", "@playwright/mcp@latest", "--headless"]
    },
    "linear": {
        "url": "https://mcp.linear.app/sse"
    },
    "sourcegraph": {
        "url": "${SRC_ENDPOINT}/.api/mcp/v1",
        "headers": { "Authorization": "token ${SRC_ACCESS_TOKEN}" }
    }
}

Many remote servers handle authentication automatically via OAuth. For servers requiring manual auth, pass headers directly or use manual OAuth registration.

MCP Server Loading Order

When the same MCP server name appears in multiple places, Amp uses this precedence (highest to lowest):

1. CLI flags (--mcp-config)
2. User/workspace config (amp.mcpServers)
3. Skills (only loaded if not already configured above)

This means you can override skill-provided MCP servers with your own configuration if needed.

Workspace MCP Server Trust

MCP servers in workspace settings (.amp/settings.json) require explicit approval before they can run. This prevents untrusted code from executing automatically when you open a project.

When a workspace MCP server is awaiting approval, you’ll see awaiting approval in amp mcp doctor output. To approve:

$ amp mcp approve my-server

In the CLI, you’ll be prompted to approve workspace servers when they’re first detected.

MCP servers in your global settings (~/.config/amp/settings.json) or passed via --mcp-config do not require approval.

MCP Best Practices

Too many available tools can reduce model performance, so for best results, be selective:

• Bundle MCP servers in skills instead of adding them globally—tools stay hidden until the skill loads.
• Use MCP servers that expose a small number of high-level tools with high-quality descriptions.
• Disable MCP tools you aren’t using, or consider using CLI tools instead.

OAuth for Remote MCP Servers

Some MCP servers like Linear support automatic OAuth client registration. When you add such a server, Amp will automatically start the OAuth flow in your browser upon startup.

$ amp mcp add my-server https://example.com/.api/mcp/v1

$ amp mcp oauth login my-server \
  --server-url https://example.com/.api/mcp/v1 \
  --client-id your-client-id \
  --client-secret your-client-secret \
  --scopes "openid,profile,email,user:all"

$ amp mcp oauth logout my-server

Permissions

Amp does not ask for approval before running tools.

The Plugin API allows you to customize this behavior.

If Amp detects amp.permissions, amp.guardedFiles.allowlist, or amp.dangerouslyAllowAll (set to false) in your settings, an internal plugin is activated to apply the legacy permissions rules.

Plugins

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

Use plugins when written guidance is not enough. Use AGENTS.md for durable instructions, skills for task-specific agent guidance, MCP and toolboxes for external tool integrations, and plugins for code that reacts to Amp events or extends Amp behavior.

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

Plugin Locations

Amp loads plugins from three locations:

• Project plugins — .amp/plugins/*.ts apply when you run Amp in that project.
• System plugins — apply across your own projects on this machine:
  • macOS: ~/.config/amp/plugins/*.ts
  • Linux: ~/.config/amp/plugins/*.ts
  • Windows: %USERPROFILE%\.config\amp\plugins\*.ts
• Global plugins — configured in workspace settings and applied to every workspace member. Global plugins are in a limited experimental release; contact us if you want to use them for security or policy enforcement.

Writing Plugins

A plugin is a TypeScript file that exports a default function. Amp passes a PluginAPI object to that function.

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

export default function (amp: PluginAPI) {
	amp.on('session.start', async (_event, ctx) => {
		await ctx.ui.notify('Plugin loaded.')
	})
}

After changing a plugin, open the command palette with Ctrl+O and run plugins: reload. Run plugins: list to see loaded plugins, their registered events, commands, and tools.

Plugin activation settings apply to both interactive amp sessions and amp --execute runs.

Amp also has a built-in skill for writing plugins, so you can just ask it to write a plugin for you.

Event Examples

Plugin events follow the agent lifecycle. A session starts first; each user turn then starts, may run tools, and eventually ends.

╭───────────────╮    ╭─────────────╮    ╭───────────╮    ╭─────────────╮    ╭───────────╮
│ session.start │───▶│ agent.start │───▶│ tool.call │───▶│ tool.result │───▶│ agent.end │
╰───────────────╯    ╰─────────────╯    ╰───────────╯    ╰─────────────╯    ╰───────────╯
                                              ▲                 │
                                              ╰──── per tool ───╯

session.start: Notify When a Plugin Loads

session.start fires when a plugin session starts. It is useful for setup, logging, and small user-visible confirmations.

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

export default function (amp: PluginAPI) {
	amp.on('session.start', async (event, ctx) => {
		const thread = event.thread ? ` for ${event.thread.id}` : ''
		await ctx.ui.notify(`Example plugin loaded${thread}.`)
	})
}

tool.call: Approve or Reject a Tool Call

tool.call fires before a tool runs. Return allow to run the tool, reject-and-continue to block it and let the agent continue, modify to change the input, or synthesize to provide a result without running the tool.

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

export default function (amp: PluginAPI) {
	amp.on('tool.call', async (event, ctx) => {
		const confirmed = await ctx.ui.confirm({
			title: `Allow ${event.tool}?`,
			message: `Amp wants to call ${event.tool}.`,
			confirmButtonText: 'Allow',
		})

		if (confirmed) {
			return { action: 'allow' }
		}

		return {
			action: 'reject-and-continue',
			message: `The user rejected ${event.tool}.`,
		}
	})
}

tool.result: Observe or Modify a Tool Result

tool.result fires after a tool finishes and before the result is sent back to the model. Return nothing to keep the original result, or return a replacement status/output.

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

export default function (amp: PluginAPI) {
	amp.on('tool.result', async (event, ctx) => {
		if (event.status === 'error') {
			await ctx.ui.notify(`Tool failed: ${event.tool}`)
		}
	})
}

agent.start: Notify When a Turn Starts

agent.start fires when the user submits a prompt. It is useful for reacting to new turns before the agent starts working.

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

export default function (amp: PluginAPI) {
	amp.on('agent.start', async (_event, ctx) => {
		await ctx.ui.notify('Amp is starting a new turn.')
	})
}

agent.end: Continue After a Turn Ends

agent.end fires when the agent finishes a turn. Return continue to append a follow-up user message and start another turn. Always include a marker or other guard when returning continue so your plugin does not loop forever.

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

const marker = '[plugin:tests-requested]'

export default function (amp: PluginAPI) {
	amp.on('agent.end', (event) => {
		if (!event.message.toLowerCase().includes('verify')) {
			return
		}
		if (event.message.includes(marker)) {
			return
		}

		return {
			action: 'continue',
			userMessage: `${marker} Before finishing, run the most relevant tests for your changes.`,
		}
	})
}

Command, Tool, and UI Examples

Add a Command

Commands appear in Amp’s command palette.

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

export default function (amp: PluginAPI) {
	amp.registerCommand(
		'open-plugin-docs',
		{
			title: 'Open plugin docs',
			category: 'docs',
			description: 'Open the Amp Plugin API manual page.',
		},
		async (ctx) => {
			await ctx.system.open('https://ampcode.com/manual/plugin-api')
		},
	)
}

Register a Tool

Tools registered by plugins are available to the model alongside Amp’s built-in tools.

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

export default function (amp: PluginAPI) {
	amp.registerTool({
		name: 'project_status',
		description: 'Show the current git status for this repository.',
		inputSchema: {
			type: 'object',
			properties: {},
			required: [],
		},
		async execute() {
			const result = await amp.$`git status --short`
			return result.stdout || 'No changes.'
		},
	})
}

Ask the User for Input

Plugins can show notifications, confirmation dialogs, text inputs, and selection dialogs.

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

export default function (amp: PluginAPI) {
	amp.registerCommand(
		'add-note-to-thread',
		{
			title: 'Add note to thread',
			category: 'notes',
			description: 'Prompt for a note and append it to the current thread.',
		},
		async (ctx) => {
			const note = await ctx.ui.input({
				title: 'Thread note',
				helpText: 'What should Amp remember in this thread?',
				submitButtonText: 'Add note',
			})

			if (!note) {
				return
			}

			await ctx.thread?.append([{ type: 'user-message', content: note }])
		},
	)
}

Classify With AI

Use amp.ai.ask(...) when a plugin needs a small yes/no classification decision with reasoning.

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

export default function (amp: PluginAPI) {
	amp.on('agent.start', async (event, ctx) => {
		const answer = await amp.ai.ask(
			`Is this request asking to change production infrastructure? ${event.message}`,
		)

		if (answer.result === 'yes') {
			await ctx.ui.notify(`This looks production-related: ${answer.reason}`)
		}
	})
}

Example Plugin: Permissions

This plugin asks the user before running potentially destructive git commands. It uses amp.ai.ask(...) to classify each git command and only prompts when the command looks risky.

Save this as .amp/plugins/no-destructive-git-operations.ts, then run plugins: reload.

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

/**
 * Plugin that prevents risky git operations by asking the user for confirmation.
 * Uses amp.ai.ask() to classify git commands as risky and prompts the user accordingly.
 */
export default function (amp: PluginAPI) {
	const safePatterns = [
		/^\s*git\s+status\b/,
		/^\s*git\s+log\b/,
		/^\s*git\s+diff\b/,
		/^\s*git\s+show\b/,
		/^\s*git\s+branch\s*$/,
		/^\s*git\s+branch\s+-[av]\b/,
		/^\s*git\s+stash\s+list\b/,
		/^\s*git\s+remote\s+-v\b/,
		/^\s*git\s+fetch\b/,
		/^\s*git\s+pull\b/,
		/^\s*git\s+add\b/,
		/^\s*git\s+commit\b/,
		/^\s*git\s+push\b(?!.*(-f|--force))/,
	]

	amp.on('tool.call', async (event, ctx) => {
		const shellCommand = amp.helpers.shellCommandFromToolCall(event)
		if (!shellCommand?.command) {
			return { action: 'allow' }
		}

		const command = shellCommand.command

		if (!/^\s*git\s+/.test(command)) {
			return { action: 'allow' }
		}

		if (safePatterns.some((pattern) => pattern.test(command))) {
			return { action: 'allow' }
		}

		const aiResponse: PluginAIAskResult = await ctx.ai.ask(
			`Does this git command look like a potentially destructive operation that could lose work? Answer yes if it's a destructive operation like force push, branch deletion, reset, or checkout to detached HEAD. Command: ${command}`,
		)

		if (aiResponse.result === 'no') {
			return { action: 'allow' }
		}

		const confirmed = await ctx.ui.confirm({
			title: 'Potentially destructive git operation',
			message: `${command}\n\nReason: ${aiResponse.reason}\n\nDo you want to proceed?`,
			confirmButtonText: 'Allow',
		})

		if (confirmed) {
			return { action: 'allow' }
		}

		return {
			action: 'reject-and-continue',
			message: `User cancelled potentially destructive git operation: ${command}`,
		}
	})
}

Example Plugin: Kitchen Sink

For a single plugin that exercises every plugin surface — events, commands, tools, UI, and AI helpers — see the Kitchen Sink example on the Plugin API reference page.

Acknowledgment

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

See the Plugin API reference for the full @ampcode/plugin type reference.

Thread Sharing

Threads are conversations with the agent, containing all your messages, context, and tool calls. Your threads are visible at ampcode.com/threads.

We find it useful to include Amp thread links in code reviews to give the reviewer more context. Reading and searching your team’s threads can also help you see what’s going on and how other people are using Amp.

To change who you’re sharing a thread with:

• In the CLI, type / for the command palette, then select thread: set visibility.
• On the web, use the sharing menu at the top.

A thread’s visibility level can be set to:

• Public: visible to anyone on your public profile (ampcode.com/@your-username), and publicly searchable
• Unlisted: visible to anyone on the internet with the link, and shared with your workspace
• Workspace-shared: visible to all members of your workspace
• Group-shared: visible to members of specific groups you choose, and workspace admins (Enterprise-only)
• Private: visible only to you (and workspace admins if you’re in a workspace)

If you are not in a workspace, your threads are only visible to you by default.

If you’re in a workspace, your threads are shared by default with your workspace members. Enterprise workspaces can configure additional sharing controls; see Workspace Thread Visibility Controls.

CLI

After installing and signing in, run amp to start the Amp CLI.

Without any arguments, it runs in interactive mode:

$ amp

If you pipe input to the CLI, it uses the input as the first user message in interactive mode:

$ echo "commit all my changes" | amp

Use -x or --execute to start the CLI in execute mode. In this mode, it sends the message provided to -x to the agent, waits until the agent ended its turn, prints its final message, and exits:

$ amp -x "what files in this folder are markdown files? Print only the filenames."
README.md
AGENTS.md

(Note: Execute mode (amp -x) consumes paid credits only. Amp Free usage only applies to interactive Amp usage.)

You can also pipe input when using -x:

$ echo "what package manager is used here?" | amp -x
cargo

If you want to use -x with the agent using tools that might require approval, make sure to either use --dangerously-allow-all or configure Amp to allow them:

$ amp --dangerously-allow-all -x "Run `sed` to replace 2024 with 2025 in README."
Done. Replaced 8 occurrences of 2024 in README.md

Execute mode is automatically turned on when you redirect stdout:

$ echo "what is 2+2?" | amp > response.txt

When you pipe input and provide a prompt with -x, the agent can see both:

$ cat ~/.vimrc | amp -x "which colorscheme is used?"
The colorscheme used is **gruvbox** with dark background and hard contrast.

```vim
set background=dark
let g:gruvbox_contrast_dark = "hard"
colorscheme gruvbox
```

You can use the --mcp-config flag with -x commands to specify an MCP server without modifying your configuration file.

$ amp --mcp-config '{"everything": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-everything"]}}' -x "What tools are available to you?"

To see more of what the CLI can do, run amp --help.

Keybindings

The most important keybinding is Ctrl+O to open the command palette. Other keybindings worth remembering:

• Ctrl+G to open the current prompt in your editor (requires `$EDITOR`)
• Ctrl+S to switch agent modes
• Ctrl+R for prompt history
• ↑/↓ to move to previous messages and edit them
• Alt+T to expand thinking/tool blocks
• Alt+D to toggle reasoning effort for the active model (e.g. smart's high/xhigh/max, or deep's medium/high/xhigh)
• @ to mention files

Use Ctrl+O to open the command palette and run amp: help to see more keybindings.

Non-Interactive Environments

For non-interactive environments (e.g. scripts, CI/CD pipelines), set your access token in an environment variable:

export AMP_API_KEY=your-access-token-here

CLI–IDE Integration

The Amp CLI integrates with VS Code, JetBrains, Neovim, and Zed (see ampcode.com/install to install), which lets the Amp CLI:

• See the current open file and selection, so Amp can understand the context of your prompt better
• Edit files through your IDE, with full undo support

Follow the instructions for your IDE. If you are using JetBrains and run the Amp CLI from a terminal other than JetBrains’ builtin terminal, run amp --jetbrains to detect it.

Writing Prompts in the CLI

In the Amp CLI, Enter submits your prompt.

Use Shift+Enter to insert a newline when your terminal supports modified Enter keys (for example Ghostty, Wezterm, Kitty, iTerm2, or tmux with extended-keys enabled).

Amp knows how to configure tmux for this, so you can ask Amp to set it up.

Use Ctrl+J to insert a newline in any terminal.

You can also type \ followed by return to insert a newline.

If you have the environment variable $EDITOR set, you can use the editor command from the command palette to open your editor to write a prompt.

Streaming JSON

Amp’s CLI supports streaming JSON output format, one object per line on stdout, for programmatic integration and real-time conversation monitoring.

Use the --stream-json flag with --execute mode to output in stream JSON format instead of plain text. If you want assistant thinking blocks in the JSON output, add --stream-json-thinking (this extends the schema and is not Claude Code compatible).

Basic usage with argument:

$ amp --execute "what is 3 + 5?" --stream-json

Combining —stream-json with amp threads continue:

$ amp threads continue --execute "now add 8 to that" --stream-json

With stdin input:

$ echo "analyze this code" | amp --execute --stream-json

You can find the schema for the JSON output in the Appendix.

Input can also be provided on stdin with the --stream-json-input flag. Each stdin line is a complete JSON object. For example, you can use jq -c to emit a text-plus-image message as a single line:

$ jq -c . <<'EOF' | amp -x --stream-json --stream-json-input
{
  "type": "user",
  "message": {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "what do you see?"
      },
      {
        "type": "image",
        "source_path": "file:///Users/alice/images/example.jpg",
        "source": {
          "type": "base64",
          "media_type": "image/jpeg",
          "data": "..."
        }
      }
    ]
  }
}
EOF

The --stream-json flag requires --execute mode. It cannot be used standalone. --stream-json-input requires --stream-json, and --stream-json-thinking implies --stream-json.

When using --stream-json-input, the behavior of --execute changes in that Amp will only exit once both the assistant is done and stdin has been closed.

This allows for programmatic use of the Amp CLI to have conversations with multiple user messages.

#!/usr/bin/env bash

send_message() {
  local text="$1"
  echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"'$text'"}]}}'
}

{
  send_message "what's 2+2?"
  sleep 10

  send_message "now add 8 to that"
  sleep 10

  send_message "now add 5 to that"
} | amp --execute --stream-json --stream-json-input

--stream-json-input messages also allow for a "steer": true attribute to be set at the top level. If the message is queued while the agent is busy, Amp marks it as steering so it is handled at the next interruption point.

See the Appendix for the schema of the output, example output, and more usage examples.

Configuration

Amp reads settings from these locations:

• Workspace settings: the nearest .amp/settings.json or .amp/settings.jsonc, searched upward from your current working directory to the repository root (or the current directory outside a git repository)
• User settings:
  • macOS: ~/.config/amp/settings.json or ~/.config/amp/settings.jsonc
  • Linux: ~/.config/amp/settings.json or ~/.config/amp/settings.jsonc
  • Windows: %USERPROFILE%\.config\amp\settings.json or %USERPROFILE%\.config\amp\settings.jsonc
• Custom user settings: pass --settings-file <path> to point Amp at a different user settings file

When the same setting appears in multiple places, workspace settings override user settings.

All settings use the amp. prefix.

Settings

Enterprise Managed Settings

Enterprise workspace administrators can enforce settings that override user and workspace settings by deploying their policies to the following locations on machines running Amp:

• macOS: /Library/Application Support/ampcode/managed-settings.json
• Linux: /etc/ampcode/managed-settings.json
• Windows: %ProgramData%\ampcode\managed-settings.json

This managed settings file uses the same schema as regular settings files, with one additional field:

Proxies and Certificates

When using the Amp CLI in corporate networks with proxy servers or custom certificates, set these standard Node.js environment variables in your shell profile or CI environment as needed:

export HTTP_PROXY=your-proxy-url
export HTTPS_PROXY=your-proxy-url
export NODE_EXTRA_CA_CERTS=/path/to/your/certificates.pem

Pricing

Amp charges you based on your actual usage of LLMs and certain other tools (like web search). We pass these costs through to you. For individuals and non-enterprise workspaces, there is zero markup on the providers’ API pricing. There is no subscription or commitment for Amp, and the minimum credit purchase is $5.

For example, if you run an Amp thread that incurs $2 in Anthropic API usage and $0.50 in OpenAI API usage, we will deduct $2.50 from your Amp credits balance.

Buy credits and check your balance in user settings or workspace settings, or by running amp usage.

Enterprise

Enterprise usage is 50% more expensive than individual and team plans, and includes access to:

• SSO (Okta, SAML, etc.) and directory sync
• Zero data retention for text inputs in LLM inference
• Advanced thread visibility controls
• Entitlements for per-user cost controls
• MCP registry allowlists
• Managed user settings
• API for workspace analytics and data management (OpenAPI schema)
• User groups for cost attribution and per-group thread visibility options (on request)
• Configurable thread retention (on request)
• IP allowlisting for workspace access (on request, extra charges apply)

For more information about Amp Enterprise security features, see the Amp Security Reference.

To start using Amp Enterprise, go to your workspace and click Plan in the top right. This requires a special one-time $1,000 USD purchase, which grants your workspace $1,000 USD of Amp Enterprise usage and upgrades your workspace to Enterprise.

Contact amp-devs@ampcode.com for access to more purchasing options and for more information about Amp Enterprise.

Notes

For detailed cost information about a thread, click the $ price on the right sidebar from any thread’s page.

All unused credits expire after one year of account inactivity. Workspace credits are pooled and shared by all workspace members.

Invoices are issued through Stripe, which supports adding your VAT ID or other tax information.

See the latest update about Amp Free.

Support

For general help with Amp, post on X and mention @AmpCode, or email amp-devs@ampcode.com. You can also join our Amp Insiders community to discuss Amp and share tips with others.

For billing and account help, contact amp-devs@ampcode.com.

Supported Platforms

Amp supports macOS, Linux, and Windows via WSL. On Windows, we recommend WezTerm or Alacritty instead of Windows Terminal, for fully functional clipboard support.

Amp’s JetBrains integration supports all JetBrains IDEs (IntelliJ, WebStorm, GoLand, etc.) on versions 2025.1+ (2025.2.2+ is recommended).