Amp Owner’s Manual

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

Why Amp?

Amp is the frontier agent.

• Multi-Model: GPT-5.6, Claude Fable 5, 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 4 modes: low (fast, low-cost mode for small, well-defined tasks), medium (balanced intelligence, speed, and cost for most tasks), high (deep reasoning for hard tasks), ultra (the most capable mode for hard, open-ended tasks).

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

Get Started

1. Sign in at ampcode.com
2. To use the Amp CLI locally or remote-controlled via the web: install the Amp CLI and run amp.
3. (Optional) Sign up for an Amp monthly subscription for included agent and orbs usage.
4. (Optional) Link your ChatGPT subscription for more GPT-5.6 usage.

You’re ready to use Amp!

Installation

Staying Current

Run amp update.

IDE integrations

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

• 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 4 modes:

• low: Fast, low-cost mode for small, well-defined tasks.
• medium: Balanced intelligence, speed, and cost for most tasks.
• high: Deep reasoning for hard tasks.
• ultra: The most capable mode for hard, open-ended tasks.

Modes are capability presets, not fixed model selectors. Amp can customize the main agent and Oracle model routing based on connected model provider subscriptions, workspace restrictions, and model availability. See Models for the current routes and subscription-specific behavior.

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

How to Prompt

For the best results, follow these guidelines:

• Be explicit with what you want. Instead of “can you do X?”, try “do X.”
• Use one thread per task. (By task we mean the casual definition of “something you need to do”.) Threads and tasks can go on forever but shouldn’t. Do not ask the agent to write database migrations in the same thread as it previously changed CSS for an unrelated 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: “Do not edit any files.”
• Use AGENTS.md files to guide Amp on how to run your tests and build steps and to avoid common mistakes.
• 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.

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)

If you’re in a workspace, use Amp’s workspace 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.

To add personal guidance to top-level agents from the web app, open Settings, select Advanced, and edit Global AGENTS.md.

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.

In the CLI, 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.

The web feed also supports URL filters you can bookmark or share. Use /feed?time=7d to change the activity window (24h, 72h, 7d, or all). Use /feed?q=label:bug to search with the thread query syntax: bare words or quoted phrases, plus filters like id:, label:, file:, project:, repo:, ref:, author:, archived:, after:, and before:. For example, /feed?q=label:bug%20after:7d shows recent threads with the bug label.

The after: and before: filters use the thread’s update time. You can also use the explicit names updated_after: and updated_before:. For example, updated_before:7d finds threads with no activity in the last week. These filters accept ISO dates, relative days, or relative weeks.

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 URL.

To archive a thread, from the command palette, run thread: archive 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.

Voice Input

By default, press Cmd+Shift+D on macOS or Ctrl+Shift+D elsewhere to start dictating. You can change this in Keyboard Shortcuts. Press the shortcut again to stop. You can also press the icon. Press and hold the shortcut or icon to dictate and send when you release it.

The portal review widget also supports dictation and uses your saved dictation shortcuts. It records from the portal hostname whether the portal is embedded in Amp or open in a separate tab, so your browser may ask for microphone permission for each portal hostname. Portal transcription sends only the recorded audio. It does not use thread messages, the comment draft, the selected page element, or your saved vocabulary as context.

Add terms that Amp mishears to your custom vocabulary. You can also run amp config vocabulary add <term>, or ask Amp to run it for you.

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

If you send a message when the agent is still working, your message is queued and will be sent when the agent is done.

Press Enter Enter to steer it sooner, which sends the message when the agent is done with its current step (such as a command or thinking block).

Press Esc Esc to forcibly stop the agent and send your message immediately, when you want to interrupt its work.

Projects

A project connects a repository to its Amp settings, secrets, and related threads. It belongs to you or to your workspace.

Projects are optional: orb threads can run with No Project, and CLI threads join a project automatically by matching the checkout’s Git remotes. Orb size, secrets and environment variables, commit author, and setup files are covered in the Orbs manual.

You can ask Puck to update a project’s name, mapped repository URL and aliases, changes workflow, commit author, or orb size. Puck uses your project permissions: a workspace project can be changed only by its creator or a workspace admin.

Repository

The repository can be an existing one — on GitHub or any Git URL — or a new one that Amp creates and hosts. Clone Amp-hosted repositories with amp clone owner/project-name (owner is the user or workspace name).

Changes Workflow

The Changes Workflow setting picks the main action in a thread’s changes sidebar: Ship commits and pushes directly to origin/main; Push to Branch pushes the current branch and, on GitHub, returns a pull request URL; and Custom Ship sends the project’s configured prompt to the agent instead of the default Ship workflow.

For automatic pull requests, add “Create pull requests with gh pr create, embedding public artifact URLs of screenshots or videos in the PR description” to your AGENTS.md (gh is preinstalled and authenticated in orbs).

Orbs

Orbs are remote machines that can run Amp threads so your laptop can do something else or take a break. Learn how to create and configure them in the Orbs manual.

Runners

You can start Amp threads remotely from ampcode.com on any machine where you can run amp.

In order to do that, you need an Amp instance that serves as a runner.

You can turn every interactive Amp TUI into a runner by setting amp.remoteThreadCreation.enabled to true. Use the command amp: enable remote creation of threads to turn it on. Each TUI will accept new threads in the directory where you started it.

Run amp --no-tui to start a runner-only Amp instance. It waits for and runs remotely created threads in the current directory without opening the TUI. Pass --runner-id <id> to give it a stable runner ID, such as amp --no-tui --runner-id grandmas-garage-server. Runner IDs must be valid hostnames and are case-insensitive; the casing you provide is preserved. To access its terminals from ampcode.com, pass --remote-control-terminal.

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.

Agent Skills

Skills are directories that contain instructions and optional resources for specific tasks. Amp includes built-in skills. You can also keep skills in a project, install them on one machine, or publish them for yourself or your workspace.

Creating and installing skills

Amp has a built-in building-skills skill that can create or install skills for you. Ask Amp:

Create a project skill for deploying this app to staging
Create a personal skill for my release notes workflow
Install the skills from github.com/example/engineering-skills

Project skills are saved under .agents/skills/ and can be committed with the project. Personal skills are available everywhere you use Amp. For direct shell installation from a GitHub repository, Git URL, or local path, run amp skill add <source>. Pass --global to install it only on the current machine under ~/.config/agents/skills/.

Skill sources and precedence

Amp uses the first skill with a given frontmatter name. The order is:

1. ~/.config/agents/skills/
2. ~/.agents/skills/
3. ~/.config/amp/skills/
4. .agents/skills/ in the project and searched parent directories
5. .claude/skills/ in those directories
6. ~/.claude/skills/
7. ~/.claude/plugins/cache/
8. Directories in amp.skills.path, in the order they are configured
9. Built-in skills
10. Your personal skills repository
11. Your active workspace skills repository

Local and built-in skills therefore mask repository skills with the same name. A personal skill masks a workspace skill with the same name. Set amp.skills.disableClaudeCodeSkills to skip the Claude-compatible locations.

Viewing and reloading skills

You can ask Amp:

List the skills available in this thread and where each one came from
Reload my skills

For direct inspection, run amp skills list, add --json for machine-readable output, or open the interactive CLI command palette with Ctrl+O and run skills: list. The reload_skills tool rescans local directories and fetches the latest personal and workspace skills. Running amp skills list in another shell does not reload an existing session.

Skill repositories

Personal skills are available everywhere you use Amp. Workspace admins manage workspace skills, which are available to everyone in the workspace. Amp stores each scope in its own Git repository.

The simplest way to manage these skills is to ask Amp in a thread. For example:

Create a personal skill for writing my release notes
Create a workspace skill for deploying our staging environment
Import this shared skill into my workspace skills: <shared-skill-url>
Update the imported release-notes skill in my workspace skills

Amp finds the right repository, makes and reviews the change in a checkout, commits it, and asks before pushing. A push publishes the skill. New threads load it automatically, and Amp can reload it in the current thread.

To share a personal skill, open Skills in Personal Settings, select the skill, choose Share, make it available to the workspace, and copy its URL. Send the URL directly or paste it into Slack, where it unfurls with details about the skill. Teammates can paste the URL into a thread or ask Amp, “Has anyone got a release-notes skill?”

If you edit a repository directly, put each skill in a top-level directory with SKILL.md directly inside it. The directory name and the name in SKILL.md must match.

release-notes/
├── SKILL.md
├── scripts/
└── references/

For direct shell access, amp skills repositories lists the repositories and clone commands. amp clone user-skills and amp clone workspace-skills clone them. The amp skill import and amp skill update commands manage shared imports. Repository owners can require signed commits in the repository’s Advanced settings.

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 help it decide when to load the skill. The rest of SKILL.md is loaded only when the skill is invoked.

Skills can include scripts, templates, and reference files in the same directory. The agent can access these files by paths relative to the skill directory.

MCP servers in skills

A skill can define MCP servers in a sibling mcp.json file or in the mcpServers field of its SKILL.md frontmatter. If both are present, Amp uses mcpServers and ignores mcp.json.

Amp connects to skill MCP servers when it discovers the skill. Tools from a server defined only by a skill stay hidden until the skill is loaded. If a server with the same name is also supplied by a CLI flag or direct configuration, that source takes precedence and its tools remain visible.

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 will sometimes spawn subagents 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 uses subagents automatically for suitable tasks, mostly in medium mode but occasionally in other modes. 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. Oracle routing depends on the agent mode, connected model provider subscriptions, workspace restrictions, and model availability. In high mode without a connected ChatGPT subscription, Oracle currently uses Claude Fable 5 with high reasoning. With a connected ChatGPT subscription, it uses GPT-5.6 Sol with high reasoning to maximize use of that subscription. The main High agent currently uses GPT-5.6 Sol with x-high reasoning in both cases. See Models for the other current routes. These mappings can change as Amp evaluates new models.

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.

Painter

Amp can generate and edit images using the Painter tool, powered by GPT Image 2.

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. Workspace config (amp.mcpServers in .amp/settings.json)
3. User config (amp.mcpServers in ~/.config/amp/settings.json)
4. Skills

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.

Note: Orbs do not yet support OAuth-authenticated MCP servers, but we will add support soon.

$ 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.

Schedules

Agents in Amp can set their own schedules and wake themselves up. When a schedule fires, the agent wakes up with its saved prompt and continues right where it left off, with all of its context and history.

Here are some examples:

• “Check on this backfill job every ten minutes and ping me on Slack if it stalls. Let me know when it’s done.”
• “Merge this, and remind me on Slack in two days to clean up the feature flag.”
• “Every morning, dig up the five slowest database queries of the past 24 hours and DM me the list on Slack.”

See the Right on Schedule announcement for more examples and details.

Plugins

Plugins are TypeScript or JavaScript modules that add tools, commands, and event-driven behavior to Amp. A plugin can be a single file or a directory with supporting files. Plugins run code in your environment, so only load plugins you trust.

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 thread-scoped yes/no decisions

Plugin Locations

Amp loads plugins from these sources:

• Project plugins. Put files or directories in .amp/plugins/. They apply when you run Amp in that project.
• System plugins. Put files or directories in ~/.config/amp/plugins/ on macOS and Linux, or %USERPROFILE%\.config\amp\plugins\ on Windows. They apply to your projects on that machine.
• Personal. Manage them in Personal Settings. They apply everywhere you use Amp.
• Workspace. Workspace admins manage them in Workspace Settings. They apply to everyone in the workspace.

A local plugin masks a personal or workspace plugin with the same name. A personal plugin masks a workspace plugin with the same name. Inside one plugin source, a root file such as foo.ts masks a foo/ directory.

Writing Plugins

A single-file plugin is a .ts or .js file directly inside a plugin location. A directory plugin uses <plugin-name>/index.ts or <plugin-name>/index.js. If both entry files exist, Amp uses index.ts. The entry file can import supporting files with relative paths.

deploy-status/
├── index.ts
├── client.ts
└── prompts/

Every plugin entry file exports a default function. Amp passes a PluginAPI object to that function.

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

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

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, ask Amp to reload it. You can also ask Amp to list the plugins available in the thread. For direct control, open the command palette with Ctrl+O and run plugins: reload or plugins: list. Run amp plugins list in a shell to see loaded plugins, their sources, registered events, commands, and tools.

Plugin UI is mirrored across TUI and Web surfaces:

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.

Plugin Repositories

Your personal plugin repository applies only to you. Workspace admins manage the workspace repository, whose plugins apply to everyone in the workspace. The simplest way to manage either is to ask Amp in a thread. For example:

Create a personal plugin that adds a tool to check our deploy status
Create a workspace plugin that blocks destructive database commands
Import this shared plugin into my workspace plugins: <shared-plugin-url>
Update the imported deploy-status plugin in my workspace plugins

Amp finds the right repository, writes and tests the plugin, commits it, and asks before pushing. A push publishes the plugin. Amp can then reload it in the current thread without restarting.

To share a personal plugin, open Plugins in Personal Settings, select the plugin, choose Share, make it available to the workspace, and copy its URL. Send the URL directly or paste it into Slack, where it unfurls with details about the plugin. Teammates can paste the URL into a thread or ask Amp, “Has anyone got a tmux plugin?”

For direct shell access, amp plugins repositories lists the repositories and clone commands. amp clone user-plugins and amp clone workspace-plugins clone them. The amp plugins import and amp plugins update commands manage shared imports. Repository owners can require signed commits in the repository’s Advanced settings.

Event Examples

Plugin events follow a thread session’s agent lifecycle. session.start is emitted for the thread session; 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: Run Setup When a Thread Starts

session.start fires when Amp starts a thread session, such as when the user sends the first message in a new thread or opens/switches to an existing thread. Put plugin-load initialization directly in the exported function body. Multiple threads can be started and continue to run at the same time in the same Amp CLI. There is no session.end event.

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

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

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')
		},
	)
}

Changing Command Availability

amp.registerCommand(...) accepts an optional availability and returns a subscription whose setAvailability(...) method updates how the command appears in the palette:

• { type: 'enabled' } — shown and selectable (the default).
• { type: 'disabled', reason: '...' } — shown but not selectable; reason is displayed alongside the command.
• { type: 'hidden' } — not shown at all.

This plugin adds two commands that toggle Amp’s built-in notifications.enabled setting and keeps the palette showing only the relevant one.

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

export default async function (amp: PluginAPI) {
	const isEnabled = (config: Record<string, unknown>) =>
		config['notifications.enabled'] !== false

	let mute: CommandSubscription | undefined
	let unmute: CommandSubscription | undefined

	const refresh = (enabled: boolean) => {
		mute?.setAvailability(enabled ? { type: 'enabled' } : { type: 'hidden' })
		unmute?.setAvailability(enabled ? { type: 'hidden' } : { type: 'enabled' })
	}

	const enabled = isEnabled(await amp.configuration.get())

	mute = amp.registerCommand(
		'mute-notifications',
		{
			title: 'Mute notifications',
			category: 'notifications',
			availability: enabled ? { type: 'enabled' } : { type: 'hidden' },
		},
		async (ctx) => {
			await amp.configuration.update({ 'notifications.enabled': false }, 'global')
			await ctx.ui.notify('Notifications muted.')
		},
	)

	unmute = amp.registerCommand(
		'unmute-notifications',
		{
			title: 'Unmute notifications',
			category: 'notifications',
			availability: enabled ? { type: 'hidden' } : { type: 'enabled' },
		},
		async (ctx) => {
			await amp.configuration.update({ 'notifications.enabled': true }, 'global')
			await ctx.ui.notify('Notifications unmuted.')
		},
	)

	amp.configuration.subscribe((config) => {
		refresh(isEnabled(config))
	})
}

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.'
		},
	})
}

Tools can also return images by returning an array of content blocks that mixes text and image blocks. For large images such as screenshots, upload the bytes with amp.attachments.upload(...) and return a URL-backed image block so thread state stores a URL instead of the base64 payload. Image uploads are validated against Amp’s inference image limits (at most 4.9 MB decoded and 8000px per dimension). Fall back to an inline base64 block if the upload fails.

async execute() {
	const png: Uint8Array = await captureScreenshot()
	try {
		const { url } = await amp.attachments.upload({ data: png, mimeType: 'image/png' })
		return [{ type: 'image', mimeType: 'image/png', url }]
	} catch {
		return [{ type: 'image', mimeType: 'image/png', data: Buffer.from(png).toString('base64') }]
	}
}

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
			}

			if (!ctx.thread) {
				await ctx.ui.notify('No active thread. Send any message to create one, then re-run this command.')
				return
			}

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

Selection dialogs can optionally append a final inline text field with Other as its placeholder. Set allowOther: true and enter a custom value directly in the list. Surrounding whitespace is trimmed, and empty values are not submitted. The promise resolves to either a listed option or the entered text, and still resolves to undefined if the user cancels.

const environment = await ctx.ui.select({
	title: 'Choose an environment',
	message: 'Select a known environment or enter another one.',
	allowOther: true,
	options: ['Development', 'Staging', 'Production'],
})

Use Thread-Scoped AI

Use amp.ai.ask(...) when a plugin needs a small yes/no classification decision with reasoning. This helper runs through the current thread; pass { threadID } when calling it outside a thread-bound handler. AI helper calls default to no reasoning; pass { reasoningEffort } to opt in for models that support it.

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

Define a Custom Agent Mode

Use amp.createAgent(...) and amp.registerAgentMode(...) to add a mode that appears alongside Amp’s built-in modes in supported clients. Run amp plugins show-agent-options to list the model IDs and built-in tools available to custom plugin agents. External plugins must include one matching // @amp-agent-mode ... metadata comment with the mode key and label for each registered mode. Clients use those comments for static discovery and show a warning toast when a runtime registration does not match its directive. Multiple mode comments in one plugin file are supported.

// @amp-agent-mode {"key":"architect","label":"architect"}

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

export default function (amp: PluginAPI) {
	const architect = amp.createAgent({
		name: 'architect',
		model: 'openai/gpt-5.5',
		instructions: [
			'You are an architecture-focused Amp mode.',
			'Before editing code, map the current design, name the tradeoffs,',
			'and prefer small changes that preserve clear module boundaries.',
		].join(' '),
		tools: 'all',
		reasoningEffort: 'high',
		display: { label: 'architect', color: '#7c3aed' },
	})

	amp.registerAgentMode({
		key: 'architect',
		description: 'Plan and implement changes with extra architecture scrutiny.',
		agent: architect.definition,
	})
}

The optional name is part of the agent’s identity. Amp includes You are <name>, a custom agent running in Amp. in the base system prompt. Omit name to avoid adding a named identity. The label only controls how the mode appears in the UI.

The optional display on createAgent travels with the agent definition, so threads created from it — including by other plugins via a thread.agent() handle — show its label and color. registerAgentMode defaults its label and color from the agent’s display; pass them explicitly to override.

Features set on createAgent are inherited by every thread created from that agent. Features passed to agent.createThread(...) are added to that list. If a registered mode requires features, include the same features list in its // @amp-agent-mode ... metadata so clients can discover the requirements before the plugin starts.

Custom mode keys and labels must be unique, non-empty, 24 characters or less, and must not conflict with built-in modes. Existing external plugins that register an agent mode without the directive continue to load and their mode remains available, but clients warn until the plugin adds matching metadata and is reloaded.

Plugin agents can create threads from interactive sessions, amp --execute, and amp --no-tui runners. Modes from a live runner can also appear in the mode picker on ampcode.com.

Define a Custom Subagent

Create an agent and expose it through a plugin tool when you want the main agent to delegate a specific kind of work on demand. The parentThreadID option keeps the subagent run connected to the thread that invoked the tool.

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

export default function (amp: PluginAPI) {
	const reviewer = amp.createAgent({
		name: 'focused-reviewer',
		model: 'openai/gpt-5.5',
		instructions: [
			'You are a focused code-review subagent.',
			'Inspect only the files and concerns named by the caller.',
			'Return concise findings with severity, evidence, and suggested fixes.',
		].join(' '),
		tools: 'all',
		reasoningEffort: 'medium',
	})

	amp.registerTool({
		name: 'focused_review_subagent',
		description: 'Run a focused code-review subagent for a specific review request.',
		inputSchema: {
			type: 'object',
			properties: {
				request: {
					type: 'string',
					description: 'The files, diff, or concern the subagent should review.',
				},
			},
			required: ['request'],
		},
		async execute(input, ctx) {
			const request = typeof input.request === 'string' ? input.request : ''
			if (!request.trim()) {
				return 'Missing review request.'
			}

			const result = await reviewer.run(request, {
				parentThreadID: ctx.thread.id,
				timeoutMs: 10 * 60 * 1000,
			})

			return result.text
		},
	})
}

Use a Built-in Agent

Use amp.getBuiltinAgent(mode) to get a handle for one of Amp’s built-in agent modes ('low', 'medium', 'high', or 'ultra') instead of defining a custom agent. The deprecated 'smart', 'deep', and 'rush' modes are still accepted but spawn threads in their replacement mode ('rush' → 'low'; 'smart'/'deep' → 'medium').

Both custom and built-in agent handles support run(message, options?) for a one-shot run and createThread(options?) for a thread you can keep appending messages to. Pass parentThreadID to connect the new thread to its parent. From a command handler without ctx.thread, use createThread({ show: true }) to create a thread and make it active in supported clients. Pass executor: 'orb' to run(...) or createThread(...) to start the thread in an orb when the current client supports orb-backed thread creation. To target a live Amp runner, pass executor: { type: 'runner', id }. For workspace Orb threads created with createThread(...), pass multiplayerTTLSeconds to enable multiplayer for 5 minutes through 7 days.

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

export default function (amp: PluginAPI) {
	const high = amp.getBuiltinAgent('high')

	amp.registerCommand(
		'start-deep-dive',
		{ title: 'Start Deep Dive', description: 'Start a background high-mode thread' },
		async (ctx) => {
			const thread = await high.createThread({
				executor: 'orb',
				multiplayerTTLSeconds: 3 * 60 * 60,
			})
			await thread.appendUserMessage({
				type: 'user-message',
				content: 'Investigate flaky tests in the CI pipeline.',
			})
			await ctx.ui.notify(`Started background thread ${thread.id}`)
		},
	)
}

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 amp.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 the core plugin surfaces — 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.

Workspaces

A workspace connects your team in Amp, with shared threads and pooled billing. Create a workspace or join one by invitation in workspace settings.

A workspace centralizes billing for its members:

• Workspace credits are pooled and shared by all workspace members. Workspace admins (or Enterprise billing managers) purchase credits for the pool and manage the workspace’s payment method.
• When you create or join a workspace, your individual paid credits are transferred to the workspace pool. They are not returned to you if you leave or are removed from the workspace. Any personal free credits you have are used before the workspace pool.
• Subscriptions remain assigned to individual members. Joining a workspace does not change or refund the current paid period; the next renewal or upgrade uses the current workspace’s billing. If the workspace paid for the current period, leaving does not change or refund that period; renewal pauses until the member resumes with personal billing. If the current period is personally funded, leaving does not pause renewal; it continues with personal billing.
• Subscription charges use the first source that can cover the full charge: eligible personal free credits, workspace free credits, workspace paid credits, then the workspace’s saved payment method.
• By default, members can start, change, cancel, and resume their own subscriptions. Subscription charges resulting from these actions can use workspace credits or the workspace’s saved payment method. Workspace admins and Billing Managers can disable member subscription management in workspace member settings and can manage member subscriptions regardless of this setting.

For SSO, thread visibility controls, and per-user cost controls, see Enterprise.

Thread Sharing

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

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 Ctrl+O 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:

• 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, and workspace admins can change the default and external sharing controls; see Workspace Thread Visibility Controls.

Multiplayer

Multiplayer lets workspace members collaborate in an orb-backed thread. Enable it from the Multiplayer chip in the thread’s title bar. Only non-private orb threads can be made multiplayer

While multiplayer is active, workspace members can send messages and access the orb’s files, changes, portals, and shared terminal.

All billing and costs for the thread and orb costs goes to the thread owner.

Multiplayer lasts three hours by default, but can be extended. Change or end it from the Multiplayer chip in the thread’s title bar, or manage all active threads from Multiplayer settings. Multiplayer mode ends automatically when the duration expires.

Security: While multiplayer is active, every workspace member can access the thread, orb, secrets, files, and terminal.

Remote Control

Remote control lets you continue a running Amp CLI thread from ampcode.com. Start Amp in the CLI, open the thread on the web (mobile or desktop), and send messages to keep working from anywhere.

To require a recent passkey authentication when interacting with the agent on the web or in the app, enable Require Passkey Authentication for Web & App Interaction in your user security settings. Workspace admins can require passkey authentication for all workspace members.

If the web Terminal says remote terminal control is disabled, restart the CLI with --remote-control-terminal, for example amp --no-tui --remote-control-terminal, then reload the thread page. Use --no-remote-control-terminal to explicitly disable access. When neither flag is provided, AMP_REMOTE_CONTROL_TERMINAL=1 enables access and AMP_REMOTE_CONTROL_TERMINAL=0 disables it. An explicit CLI flag takes precedence over the environment variable. The runner reattaches its existing threads, so you do not need to create a new thread.

Slack

Use Amp from Slack by mentioning @Amp in a channel or thread. Messages are sent to your personal Puck, which can answer questions, find and manage existing threads, and start new threads.

To install and connect the Slack integration:

1. Open Workspace Integrations as an Amp workspace admin, select Connect a Slack Workspace, and authorize the Amp app in Slack.
2. You can also link your Amp user directly with your Slack user in Personal Integrations.
3. Mention @Amp in any Slack channel or thread to summon your personal Puck.

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

You can also pipe input when using -x:

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

Interactive CLI threads remember whether the last thread used Fast mode. Execute mode and other noninteractive thread creation default to Standard mode each time. Pass --fast to enable Fast mode for one invocation; it is an alias for --features fast and works with -x and piped input.

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?"

If your plugins rely on the agent.start and agent.end lifecycle events, use the --plugin-ready-timeout flag to make execute mode wait for plugins to become ready before running the turn. Without it, the turn can start before plugins finish loading, and those events are skipped. The bare flag waits up to 10 seconds; pass a number of seconds for a different limit (maximum 300, 0 disables the wait). The wait is only an upper bound — the turn starts as soon as plugins are ready.

$ amp -x "summarize this repo" --plugin-ready-timeout
$ amp -x "summarize this repo" --plugin-ready-timeout 30

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

Keybindings

Amp’s most important keyboard shortcut is Ctrl+O to open the command palette. Other shortcuts 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 queued and previous messages and edit them
• Alt+T to expand thinking/tool blocks
• Alt+D to toggle reasoning effort for the active model where supported
• Alt+R to toggle fast mode for the active model
• Ctrl+\ to show, focus, or hide the thread sidebar
• Ctrl+C Ctrl+N to archive the current thread and start a new one
• Ctrl+C Ctrl+E to archive the current thread and quit
• Ctrl+C Ctrl+C to quit
• @ to mention files

To see the full map of keyboard shortcuts and all available commands, run amp config keymap.

For app and web shortcuts, see Keyboard Shortcuts in your personal settings.

You can customize the CLI keymap with the amp.keymap setting:

{
  "amp.keymap": {
    "mode.toggle": ["ctrl+s", "ctrl+j"],
    "thread.copyURL": "<leader> u"
  }
}

Separate keys with spaces to define a chord, such as ctrl+c ctrl+e. The key <leader> u means pressing Ctrl+X then pressing u. To change the <leader> key, define a keymap entry for "leader". Configuring a command replaces its default key or chord. Use an array to keep the old shortcut and add another one. Set a command’s entry to null to unbind its default entirely.

Unlike for other settings, keymaps in your user settings file (~/.config/amp/settings.json) override workspace entries (.amp/settings.json).

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, 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.

The JetBrains plugin is deprecated. Existing installations continue to work with amp --jetbrains, but the plugin does not receive updates.

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:

• 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
• 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)
• Custom user settings: pass --settings-file <path> to point Amp at a different user settings file

Run amp config edit to open your user settings file in $EDITOR, or add --workspace to edit workspace settings.

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

An Amp monthly subscription is the best way to start using Amp and includes agent and orbs usage. You can also link your ChatGPT subscription for more GPT-5.6 usage.

If you exceed your subscription’s included usage, 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. Paid credits require no subscription or commitment.

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)
• Regional endpoint support for bring-your-own-key model providers

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 deprecated JetBrains integration supports all JetBrains IDEs (IntelliJ, WebStorm, GoLand, etc.) on versions 2025.1+ (2025.2.2+ is recommended). Existing installations continue to work, but the plugin does not receive updates.