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

Introduction

What is Amp?

Amp is an agentic coding tool built by Sourcegraph. It runs in VS Code (and compatible forks like Cursor, Windsurf, and VSCodium) and as a command-line tool. It’s also multiplayer — you can share threads and collaborate with your team.

Principles

1. Amp is unconstrained in token usage (and therefore cost). Our sole incentive is to make it valuable, not to match the cost of a subscription.
2. No model selector, always the best models. You don’t pick models, we do. Instead of offering selectors and checkboxes and building for the lowest common denominator, Amp is built to use the full capabilities of the best models.
3. We assume that you want to access the raw power these models have to offer. In a sense, when you’re using Amp, you aren’t using Amp — you’re talking directly to a model and Amp is the shell around your conversation with the model.
4. Built to evolve. Products that lock themselves into specific model behaviors become obsolete in months. We stay current with the best, not tied to the past.

Getting Started

Install

Sign in to ampcode.com and follow the instructions for VS Code, Cursor, and Windsurf to install the extension and authenticate. You can also use the Install button at the bottom of the page for quick access to installation instructions for all platforms.

Command Line Interface

npm install -g @sourcegraph/amp

amp

echo "What is today's date?" | amp

pnpm add -g @sourcegraph/amp

amp

echo "What is today's date?" | amp

yarn global add @sourcegraph/amp

amp

echo "What is today's date?" | amp

npx @sourcegraph/amp

echo "What is today's date?" | npx @sourcegraph/amp

For non-interactive environments (e.g. scripts, CI/CD pipelines), you’ll need to export your API key as an environment variable:

export AMP_API_KEY=your-api-key-here

Using Amp

How to Prompt

Amp currently uses Claude Sonnet 4 for most tasks. 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 AGENT.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 webview 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 on a team, use Amp’s thread sharing to learn from each other.

AGENT.md

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

Amp includes AGENT.md files automatically:

• AGENT.md files in the current working directory (or editor workspace roots) and parent directories are always included.
• Subtree AGENT.md files are included when the agent reads a file in the subtree.
• $HOME/.config/AGENT.md is always included.

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

To see the agent files that Amp is using in the editor extension, hover the X% of 168k indicator in the reply area after you’ve sent the first message in a thread.

Writing AGENT.md Files

Amp offers to generate an AGENT.md file for you if none exists. You can create or update any AGENT.md files manually or by asking Amp (“Update AGENT.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 @rules/internal-api-conventions.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.
• Globs are not supported.

Uploading Images

Amp supports image uploads, allowing you to share screenshots, diagrams, and visual references with the AI. Images can provide important context for debugging visual issues or understanding UI layouts.

In the editor extension, you can:

• Copy and paste directly into the input area
• Hold Shift while dragging files over the input area

In the CLI, you can instruct Amp to take screenshots and read images from the file system by asking it to analyze specific image files by path.

Thinking Hard

If Extended Thinking is enabled (it is by default), Amp can dynamically adjust the thinking budget given to Claude Sonnet 4. The higher the budget, the more tokens it uses to “think”.

If you tell the model to “think hard” (or “think a lot” and variations) the thinking budget will be more than doubled.

If you tell the model to “think really hard” (or “think very hard”) it will be increased even more.

Mentioning Files

You can mention files directly in your prompts by typing @ followed by a pattern to fuzzy-search. It can help speed up responses by avoiding the need to search the codebase.

Keyboard Shortcuts

Shortcuts for macOS and VS Code

Shortcuts for macOS and Cursor

Shortcuts for macOS and Windsurf

Shortcuts for Windows and VS Code

Shortcuts for Windows and Cursor

Shortcuts for Windows and Windsurf

Shortcuts for Linux and VS Code

Shortcuts for Linux and Cursor

Shortcuts for Linux and Windsurf

Threads

Threads are conversations with the agent, containing all your messages, context, and tool calls. Your threads are synced to ampcode.com. If you’re on a team, your threads are also shared with your team by default, just like Git branches on a shared remote repository.

Including links to Amp threads with your changes when submitting for code review helps provide context. Reading and searching your team’s threads can help you see what’s going on and how other people are using Amp.

Privacy & Permissions

Threads can be public (visible to anyone on the internet with the link), team-shared (visible to your team members), or private (visible only to you).

If you’re on a team, your threads are shared by default with your team members.

If you are not on a team, your threads are only visible to you by default.

You can change a thread’s visibility at any time through the sharing menu at the top of the thread.

Managing Context

As you work with Amp, your thread accumulates context within the model’s context window. Amp shows your context window usage and warns when approaching limits.

When approaching the thread context limit, you can hover over the context window indicator and use the following:

• Compact Thread — Summarizes the existing conversation to reduce context usage while preserving important information
• New Thread with Summary — Creates a new thread that starts with a summary of the current conversation

File Changes

Amp tracks changes that the agent makes to files during your conversation, which you can track and revert:

• Hover over the files changed indicator (located just above the message input) to see which files were modified and by how much
• Revert individual file changes, or all changes made by the agent

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

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 uses a custom model that was trained to understand what you are trying to do next, based on your recent changes, your language server’s diagnostics, and what we call semantic context.

Amp Tab can suggest regular single or multi-line edits to change entire code blocks, next to your cursor or farther away, somewhere else in your current document.

Enabling

Enable Amp Tab by setting "amp.tab.enabled": true in your editor settings.

How to Use

• Begin typing in your editor. Amp Tab automatically presents relevant suggestions.
• Press the Tab key to accept and apply the suggested edits.
• Press the Tab key again to instantly jump to additional edits further from your cursor.
• To ignore suggestions, simply continue typing or press Esc.

If you’re using Vim extensions in VS Code and 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.

Currently, Amp Tab is free to use as a research preview for all Amp users.

Teams

Teams provide collaborative workspaces where knowledge can be shared across your organization. Create a team from the settings page. To join a team, you need an invitation from an existing team member.

Sharing

Team threads are visible to all team members by default, making it easy to learn from others and build on their work.

Team Usage

Teams provide pooled billing of usage, making it easier to manage costs across your organization. If a member of your team joins with free personal usage available, their free usage will be used before the paid team usage.

Leaderboard

Each team includes a leaderboard that tracks thread activity and contributions from team members, encouraging engagement and highlighting active participants.

Tools

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

Amp comes with a curated set of built-in tools specifically designed for coding. You can find the list of built-in tools inside Amp’s extension settings.

Custom Tools (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.

Configuration options for local (STDIO) MCP servers:

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

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

• url - server endpoint

If the remote MCP server requires authorization with OAuth, you can use mcp-remote.

Example configuration:

"amp.mcpServers": {
    "playwright": {
        "command": "npx",
        "args": ["-y", "@playwright/mcp@latest", "--headless", "--isolated"]
    },
    "semgrep": {
        "url": "https://mcp.semgrep.ai/mcp"
    },
    "linear": {
        "command": "npx",
        "args": [
            "mcp-remote",
            "https://mcp.linear.app/sse"
        ]
    }
}

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.

Command Allowlisting

Amp has a built-in safety system specifically for terminal commands that determines which commands require explicit permission before execution.

By default, Amp automatically allows certain read-only and safe commands like ls, cat, and git status. Common development commands like go test, cargo build, and pnpm run build are also pre-approved. For all other commands, Amp will prompt for permission before execution to protect your system.

You can configure Amp to execute additional commands without prompting for permission each time by adding them to the "amp.commands.allowlist" array in your extension or CLI settings:

"amp.commands.allowlist": [
    "pnpm exec tsc --build",
    "pnpm -C web check",
    "npm run *",
    "pnpm -C server test"
]

Both the editor extension and CLI use this same setting format. You can use simple command patterns like make build or wildcards like npm run * to allow multiple similar commands.

To trust the agent fully, disabling all confirmation prompts (including for commands), you can enable the following setting:

"amp.dangerouslyAllowAll": true

In the CLI, you can additionally enable this behavior temporarily for the duration of the current thread, by passing the --dangerously-allow-all argument.

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 more powerful 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. Currently that more powerful model is OpenAI’s o3.

This model is available to Amp’s main agent through a tool called oracle.

The main agent can autonomously decide to ask the oracle for help when debugging or reviewing a complex piece of code. We consciously haven’t pushed the main agent to constantly use the more powerful model yet, 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.”

JetBrains

Run amp --jetbrains to connect Amp to a JetBrains IDE (IntelliJ, WebStorm, GoLand, etc.). When running inside the integrated JetBrains terminal, the --jetbrains flag is enabled automatically.

This integration supports:

• Message Context — Amp includes the current file and selection in every message.
• Compiler Diagnostics — Amp reads type errors from the JetBrains type checker.
• File Edits — Amp edits files through the IDE so you can undo changes inside the editor.

Limitations:

• You must install the JetBrains MCP Server plugin and have your IDE running.
• Only one JetBrains IDE can be open at a time.
• Only one project can be open at a time.
• You must run amp --jetbrains from the root of your open JetBrains project, or run amp from the integrated JetBrains terminal.
• Unlike in VS Code, Amp does not include your JetBrains cursor location with every message due to this issue. A workaround is to select text instead to include it as automatic context for the model.

Importantly, you don’t have to configure the JetBrains MCP server via "amp.mcpServers" when using this integration.

Configuration Settings

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:

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

All settings use the amp. prefix.

Settings

Editor Extension and CLI

Editor Extension Only

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

Account

Security

See the Amp Security Reference document.

Signup Restrictions

If you see a “Signup is restricted” message, this likely means we cannot provide access to your region due to US export restrictions. Amp is available in most countries worldwide, but we cannot provide access to countries under US embargo to comply with applicable laws. If you believe this is a mistake, please contact support@sourcegraph.com.

Support & Community

Join the Amp Discord to connect with the Amp team and other Amp users, share tips and tricks, and get help from the community.

For billing questions, contact amp-billing-help@sourcegraph.com.

Pricing

Prepay only

Amp uses prepaid credits. You’ll never be charged more than you prepay — unless you turn on auto-reload.

Usage

Upon signing up, most users get $10 USD in free usage. You can purchase more as an individual or for your team. Unused credits expire after one year of account inactivity.

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

Enterprise

Enterprise usage is 50% more expensive than individual and team usage, and includes SSO (Okta, SAML, etc.) and zero data retention for text inputs in LLM inference. See Amp Security Reference for more information.

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

With Amp Enterprise Premium, invoice payments are offered for purchases of $5,000+ USD, and volume discounts are available for purchases of $25,000+ USD. Contact amp-devs@sourcegraph.com for access to these purchasing options and for general information about Amp Enterprise.