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.5, GPT-5.1, 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 2 modes: smart (unconstrained state-of-the-art model use) and rush (faster, cheaper, suited for small, well-defined tasks). New users receive a $10 daily grant for free usage across all modes.

Want to go much deeper? Watch our Raising an Agent podcast that chronicles the first few months of building Amp, and see our FIF.

Get Started

1. Sign into ampcode.com/install.
2. Follow the instructions to install the Amp CLI and editor extensions for VS Code, Cursor, Antigravity, JetBrains, Neovim, and other editors.

You’re ready to start using Amp!

From the Command Line

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

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.

From Your Editor

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

• VS Code, Cursor, Antigravity (and other forks): Install the sourcegraph.amp extension from the VS Code Marketplace or Open VSX Registry.
• 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.

Using Amp

Agent Modes

Amp has 2 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.

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, or select the mode in the prompt field of the editor extension.

How to Prompt

Amp currently uses Claude Opus 4.5 for most tasks, with up to 200k tokens of context. 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. That’s why we use Cmd/Ctrl+Enter to submit a message in Amp — it’s a reminder to put effort into a prompt.

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.

File	Examples
AGENTS.md in cwd, parent dirs, & subtrees	Architecture, build/test commands, overview of internal APIs, review and release steps
$HOME/.config/amp/AGENTS.md $HOME/.config/AGENTS.md	Personal preferences, device-specific commands, and guidance that you're testing locally before committing to your repository

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.
• Both $HOME/.config/amp/AGENTS.md and $HOME/.config/AGENTS.md are 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, run /agent-files (CLI) or hover the X% of 968k indicator after you’ve sent the first message in a thread (editor extension).

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__/*"]

Migrating to AGENTS.md

• From Claude Code: mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md, and repeat for subtree CLAUDE.md files
• From Cursor: mv .cursorrules AGENTS.md && ln -s AGENTS.md .cursorrules and then add @.cursor/rules/*.mdc anywhere in AGENTS.md to include all Cursor rules files.
• From existing AGENT.md: mv AGENT.md AGENTS.md (optional - both filenames continue to work)

Handoff

Amp works best when you keep threads small and focused on a single task

To continue your work from one thread in a new thread, use the handoff command from the command palette to draft a new thread with relevant files and context from the original thread.

Provide some help to the handoff command to direct the new prompt. For example:

• now implement this for teams as well, not just individual users
• execute phase one of the created plan
• check the rest of the codebase and find other places that need this fix

See Handoff (No More Compaction) for why Amp doesn’t support compaction.

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

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 or Thread: Archive in the editor extension.

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.

In the editor extension, paste an image using Cmd+V/Ctrl+V, or hold Shift and drag an image over the message field.

You can also @-mention images by file path.

Mentioning Files

Type @ to search for a file to mention.

Edit & Undo

Editing a prior message in a thread automatically reverts any changes the agent made after that message.

To edit a prior message in the CLI, press Tab to navigate to prior messages. In the editor extension, scroll up in the thread and click on a prior message.

You can also revert individual file changes by clicking the N files changed indicator.

Queueing Messages

You can queue messages to be sent to the agent once it ends its turn, without interrupting its current work. To queue a message:

• In the editor extension, type your message and press Cmd-Shift-Enter (macOS) or Ctrl-Shift-Enter (Windows/Linux).
• In the CLI, use the queue command from the command palette.

Custom Commands

Access custom commands via the Amp Command Palette: Cmd/Alt-Shift-A in VS Code/Cursor/Windsurf/Antigravity or Ctrl-O in the CLI.

You can create custom commands to reuse prompts and automate workflows.

To create a custom command, create a Markdown file or an executable in one of the following locations:

• .agents/commands in the current workspace
• ~/.config/amp/commands (uses the $XDG_CONFIG_HOME directory if set)

Each file in these directories, if it’s a Markdown file ending in .md or an executable file (having the execute bit set or a shebang on the first line), will be turned into a custom command. The name of the command will be the filename without the extension.

When invoked, custom commands append their output to the prompt input. Markdown files append their contents directly. Executable files run and append their combined stdout/stderr output (max 50k characters). Executables can also take arguments which will be passed when invoked.

Here are two examples:

• The file .agents/commands/pr-review.md will be turned into the custom command pr-review and the contents of pr-review.md will be inserted into the prompt input.
• ~/.config/amp/commands/outline is an executable that will be turned into the custom command outline and can be used with arguments: outline src/utils

Real-world examples:

• work-on-linear-issue
• resolve-pr-comments
• code-review.md

Amp Tab

Amp Tab is our in-editor completion engine, designed to anticipate your next actions and reduce the time spent manually writing code. It’s only available in VS Code and forks thereof.

It uses a custom model that we’ve trained to understand what you are trying to do next, based on your recent changes, your language server’s diagnostics, and other semantic context.

Accept a suggestion with Tab, or reject with Esc.

Note for users of Vim extensions in VS Code

If you need to press Esc twice to dismiss suggestions and enter normal mode, configure `amp.tab.dismissCommandIds` to specify which commands should run on Esc. Defaults cover popular extensions like VSCodeVim and vscode-neovim.

Keyboard Shortcuts

Shortcuts for macOS and VS Code

Command	Shortcut
New Thread	CmdL
Focus/Hide Amp Sidebar	CmdI
Switch to Thread	CmdK
Go to Next Thread	CmdShift]
Go to Previous Thread	CmdShift[

Shortcuts for macOS and Cursor

Command	Shortcut
New Thread	CmdOptionJ
Focus/Hide Amp Sidebar	CmdOptionU
Switch to Thread	CmdK
Go to Next Thread	CmdShift]
Go to Previous Thread	CmdShift[

Shortcuts for macOS and Windsurf

Command	Shortcut
New Thread	CmdOptionJ
Focus/Hide Amp Sidebar	CmdOptionU
Switch to Thread	CmdK
Go to Next Thread	CmdShift]
Go to Previous Thread	CmdShift[

Shortcuts for macOS and Antigravity

Command	Shortcut
New Thread	CmdOptionJ
Focus/Hide Amp Sidebar	CmdOptionU
Switch to Thread	CmdK
Go to Next Thread	CmdShift]
Go to Previous Thread	CmdShift[

Shortcuts for Windows and VS Code

Command	Shortcut
New Thread	CtrlL
Focus/Hide Amp Sidebar	CtrlI
Switch to Thread	CtrlK
Go to Next Thread	CtrlShift]
Go to Previous Thread	CtrlShift[

Shortcuts for Windows and Cursor

Command	Shortcut
New Thread	CtrlAltJ
Focus/Hide Amp Sidebar	CtrlAltU
Switch to Thread	CtrlK
Go to Next Thread	CtrlShift]
Go to Previous Thread	CtrlShift[

Shortcuts for Windows and Windsurf

Command	Shortcut
New Thread	CtrlAltJ
Focus/Hide Amp Sidebar	CtrlAltU
Switch to Thread	CtrlK
Go to Next Thread	CtrlShift]
Go to Previous Thread	CtrlShift[

Shortcuts for Windows and Antigravity

Command	Shortcut
New Thread	CtrlAltJ
Focus/Hide Amp Sidebar	CtrlAltU
Switch to Thread	CtrlK
Go to Next Thread	CtrlShift]
Go to Previous Thread	CtrlShift[

Shortcuts for Linux and VS Code

Command	Shortcut
New Thread	CtrlL
Focus/Hide Amp Sidebar	CtrlI
Switch to Thread	CtrlK
Go to Next Thread	CtrlShift]
Go to Previous Thread	CtrlShift[

Shortcuts for Linux and Cursor

Command	Shortcut
New Thread	CtrlAltJ
Focus/Hide Amp Sidebar	CtrlAltU
Switch to Thread	CtrlK
Go to Next Thread	CtrlShift]
Go to Previous Thread	CtrlShift[

Shortcuts for Linux and Windsurf

Command	Shortcut
New Thread	CtrlAltJ
Focus/Hide Amp Sidebar	CtrlAltU
Switch to Thread	CtrlK
Go to Next Thread	CtrlShift]
Go to Previous Thread	CtrlShift[

Shortcuts for Linux and Antigravity

Command	Shortcut
New Thread	CtrlAltJ
Focus/Hide Amp Sidebar	CtrlAltU
Switch to Thread	CtrlK
Go to Next Thread	CtrlShift]
Go to Previous Thread	CtrlShift[

Tools are what the underlying model uses to assist with tasks. For the highest quality results we recommend you use a curated set of tools, with prompts adjusted to fit the underlying model.

Built-in Tools

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

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 specialized packages of instructions and resources that teach the agent how to perform specific tasks.

Installing Skills

You can install skills from GitHub or local sources. See amp-contrib for curated skills.

CLI:

# Install all skills from a GitHub repository
amp skill add ampcode/amp-contrib

# Install a specific skill from GitHub
amp skill add ampcode/amp-contrib/tmux

# Install from a git URL
amp skill add https://github.com/ampcode/amp-contrib.git

# List installed skills
amp skill list

# Remove a skill
amp skill remove tmux

# Overwrite an existing skill
amp skill add ampcode/amp-contrib/tmux --overwrite

# Install with a custom name
amp skill add ampcode/amp-contrib/tmux --name my-tmux

VS Code and CLI Command Palette:

• /skill-add — Install skills (supports owner/repo or local path)
• /skill-list — List installed skills
• /skill-remove — Remove an installed skill

Skills are installed to .agents/skills/ in your workspace.

When installing from a GitHub repository, Amp searches for skills in these locations (in order):

• The specified path directly (e.g., ampcode/amp-contrib/tmux)
• skills/<path>
• .agents/skills/<path>

When no specific skill is specified, it searches:

• Repository root
• skills/
• .agents/skills/
• .claude/skills/

Any directory containing a SKILL.md file is recognized as a skill.

Manual Installation

You can also manually add skills by placing a SKILL.md file in a directory in:

• .agents/skills/ in your workspace root (recommended)
• ~/.config/agents/skills/ in your home directory

Amp is also compatible with .claude/skills/ in your workspace root and reads in your skills.

Skill Format

Each skill is a directory containing a SKILL.md file (case-insensitive) with the skill definition. The directory can also include additional resources like scripts, templates, or an mcp.json for bundled MCP servers.

The SKILL.md file must have YAML frontmatter with name and description:

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

# My Skill Instructions

Detailed instructions for the agent...

The description should tell the model when to use the skill and what it is for. Once the model loads the skill, it sees the entire content of the SKILL.md file.

When you have skills available, Amp will see them and can load them using the load_skill tool when needed. The skill’s content is then injected into the context.

Creating Skills

To create a new skill, ask Amp to “create a skill for [task]” or “build a skill that [does something]”. Amp has a built-in building-skills skill that guides it through creating properly structured skills with the correct format and best practices.

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

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, with reasoning level medium (which we’ve found to work well without taking an inordinate amount of time).

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

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.

MCP

You can add additional tools using MCP (Model Context Protocol) servers, which can be either local or remote. These can be configured in amp.mcpServers in your configuration file. You can also press + Add MCP Server under Settings in the VS Code.

Configuration options for local MCP servers:

• command - executable
• args - command arguments (optional)
• env - environment variables (optional)

Configuration options for remote (HTTP/SSE) MCP servers:

• url - server endpoint
• headers - HTTP headers to send with requests (optional)

Amp automatically detects the appropriate transport type (HTTP or SSE) based on the server’s response headers.

There are two ways to authenticate MCP servers:

• If the remote MCP server requires authorization, you can pass authentication headers directly via the headers option.
• For OAuth authentication, use Amp’s built-in OAuth support (see OAuth for Remote MCP Servers below).

You can also use environment variables in the configuration with the ${VAR_NAME} syntax.

Example configuration:

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

You can also add MCP servers using the CLI with header options:

$ amp mcp add sourcegraph --header "Authorization=token sgp_your-token-here" https://sourcegraph.example.com/.api/mcp/v1

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.

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

• Use MCP servers that expose a small number of high-level tools with high-quality descriptions.
• Disable MCP tools that you aren’t using, by hovering over a tool name in the extension’s Settings interface and clicking so it’s shown as tool_name, or by adding them to amp.tools.disable in your configuration file.
• Consider using CLI tools instead of MCP servers.

OAuth for Remote MCP Servers

Amp supports OAuth authentication for remote MCP servers. There are two authentication flows available:

Dynamic Client Registration (DCR)

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 linear https://mcp.linear.app/sse

Manual OAuth Client Registration

For servers that require manual OAuth client configuration:

1. Create an OAuth client in the server’s admin interface with:

   • Redirect URI: http://localhost:8976/oauth/callback
   • Required scopes for your use case

2. Add the MCP server to your configuration:

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

3. Register your OAuth credentials:

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

Upon startup, Amp will open your browser to complete the authentication flow.

OAuth tokens are stored securely in ~/.amp/oauth/ and are automatically refreshed when needed.

Permissions

Before invoking a tool, Amp checks the user’s list of permissions for the first matching entry to decide whether to run the tool.

If no match is found, Amp scans through its built-in permission list, rejecting the tool use in case no match is found there either.

The matched entry tells Amp to either allow the tool use without asking, reject the tool use outright, ask the operator, or delegate the decision to another program.

Permissions are configured in your configuration file under the entry amp.permissions:

"amp.permissions": [
  // Ask before running command line containing git commit
  { "tool": "Bash", "matches": { "cmd": "*git commit*" }, "action": "ask"},
  // Reject command line containing python or python3
  { "tool": "Bash", "matches": { "cmd": ["*python *", "*python3 *"] }, "action": "reject"},
  // Allow all playwright MCP tools
  { "tool": "mcp__playwright_*", "action": "allow"},
  // Ask before running any other MCP tool
  { "tool": "mcp__*", "action": "ask"},
  // Delegate everything else to a permission helper (must be on $PATH)
  { "tool": "*", "action": "delegate", "to": "my-permission-helper"}
]

Using Permissions in VS Code

Complex objects must be configured in VS Code’s Settings JSON.

A JSON schema for permissions is integrated into VS Code to offer guidance when editing permissions.

Rules with action ask only work for the Bash tool in VS Code.

Using Permissions in the CLI

Using amp permissions edit you can edit your permissions rules programmatically and interactively using $EDITOR.

The amp permissions test command evaluates permission rules without actually running any tools, providing a safe way for verifying that your rules work as intended.

$ amp permissions edit <<'EOF'
allow Bash --cmd 'git status' --cmd 'git diff*'
ask Bash --cmd '*'
EOF
$ amp permission test Bash --cmd 'git diff --name-only'
tool: Bash
arguments: {"cmd":"git diff --name-only"}
action: allow
matched-rule: 0
source: user
$ amp permission test Bash --cmd 'git push'
tool: Bash
arguments: {"cmd":"push"}
action: ask
matched-rule: 1
source: user

Running amp permissions list displays known permissions rules in the same format understood by amp permissions edit:

$ amp permissions list
allow Bash --cmd 'git status' --cmd 'git diff*'
ask Bash --cmd '*'

Refer to the output of amp permissions --help for the full set of available operations.

Delegating Permissions Decisions to an External Program

For full control, you can tell Amp to consult another program before invoking a tool:

{ "action": "delegate", "to": "amp-permission-helper", "tool": "Bash" }

Now every time Amp wants to run a shell command, it will invoke amp-permission-helper:

#!/usr/bin/env python3
import json, sys, os

tool_name = os.environ.get("AGENT_TOOL_NAME")
tool_arguments = json.loads(sys.stdin.read())

# allow all other tools
if tool_name != "Bash":
    sys.exit(0)

# reject git push outright - stderr is passed to the model
if 'git push' in tool_arguments.get('cmd', ''):
    print("Output the correct command line for pushing changes instead", file=sys.stderr)
    sys.exit(2)

# ask in any other case
sys.exit(1)

The error code and stderr are used to tell Amp how to proceed.

See the Appendix for the full technical 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.
• In the editor extension or 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; Enterprise workspaces only
• Private: visible only to you

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

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.

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, and Neovim (see ampcode.com/install to install), which lets the Amp CLI:

• Read diagnostics, such as typechecker and linter errors
• 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

The CLI automatically detects when you have an Amp editor extension running in most cases. If you are using JetBrains and run the Amp CLI from a terminal other than JetBrains’ builtin terminal, you need to run amp --jetbrains to detect it.

Shell Mode

Execute shell commands directly in the CLI by starting your message with $. The command and its output will be included in the context window for the next message to the agent.

Use $$ to activate incognito shell mode, where commands execute but aren’t included in the context. This is useful for noisy commands or quick checks you’d normally run in a separate terminal.

Writing Prompts in the CLI

In modern terminal emulators, such as Ghostty, Wezterm, Kitty, or iTerm2, you can use shift-enter to insert a newline in your prompts.

Additionally you can also use 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.

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 be also be provided on stdin with the --stream-json-input flag:

$ echo '{
  "type": "user",
  "message": {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "what is 2+2?"
      }
    ]
  }
}' | amp -x --stream-json --stream-json-input

The --stream-json flag requires --execute mode. It cannot be used standalone. And --stream-json-input requires --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

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

Configuration

Amp can be configured through settings in your editor extension (e.g. .vscode/settings.json) and the CLI configuration file.

The CLI configuration file location varies by operating system:

• macOS: ~/.config/amp/settings.json
• Linux: ~/.config/amp/settings.json
• Windows: %USERPROFILE%\.config\amp\settings.json

All settings use the amp. prefix.

Settings

Editor Extension and CLI

CLI-only

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: C:\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

Free

Amp gives most users a $10 daily grant for free usage of all modes and models, including Opus 4.5. This is supported by ads and may change.

Your daily grant meets all of the stringent security standards of paid usage. You are not required to share your data for training.

One account per person. Any behavior that looks like circumventing your usage limits or violating our Acceptable Use Policy will result in your account being suspended.

Paid Usage

After you’ve used up your daily free grant (or if you’ve disabled it or are ineligible), Amp consumes paid credits.

You can buy more credits in user settings for yourself, or for your team in workspace settings. Upon signup, most users receive $10 USD in free credits.

Usage is consumed based on LLM usage and usage of certain other tools (like web search) that cost us to serve. We pass these costs through to you directly with no markup, for individuals and non-enterprise workspaces.

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

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

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
• Managed user settings
• APIs for workspace analytics and data management
• Configurable thread retention (on request)
• IP allowlisting for workspace access (on request)

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. Amp Enterprise also includes access to:

• Entitlements for per-user cost controls
• User groups for cost attribution and per-group thread visibility options (on request)

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

Support

For general help with Amp, post on X and mention @AmpCode, or email amp-devs@ampcode.com. You can also join our community Build Crew 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 (WSL recommended).

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