How to use Amp: a step-by-step guide to the Amp CLI

To use Amp, you install the CLI with curl -fsSL https://ampcode.com/install.sh | bash, sign in with amp login, run amp inside a project and describe what you want. Before the first message you pick a mode on the Dial (low, medium, high or ultra) with Ctrl+S. Amp then reads your code, edits files and runs commands, and the whole conversation is saved as a thread you can reopen or share.

That’s the core loop. This guide covers the rest: logging in for scripts and CI, the shortcuts you’ll use every day, modes, subagents like the oracle, settings.json, AGENTS.md, MCP servers, execute mode, what Amp costs, and how to run it next to other CLI agents. Everything here is based on Amp’s official docs as of October 2026.

What Amp is

Amp is a coding agent and development environment. It began inside Sourcegraph and has been made by an independent company since it spun out in December 2025. It isn’t tied to one model vendor: Amp picks the model for you based on the mode you choose, and it can use your ChatGPT subscription, your Claude subscription (in its Claude Code mode) or your own API keys.

You can use it in three places: the web app at ampcode.com (no install), the macOS, iPhone, iPad and Android apps, and the terminal CLI, which is what this guide is about. Every conversation is a thread with its own URL. Amp can also run a thread on an orb, a machine Amp creates for that thread on its servers, or on a runner you host yourself.

Step 1: install the CLI

The CLI supports macOS, Linux and Windows through WSL. On Windows, the docs suggest WezTerm or Alacritty over Windows Terminal, because clipboard support is better there. The install page also has Windows and Homebrew tabs.

Amp updates itself in the background. amp update updates by hand, amp version shows what you have, and amp --help lists every command. Shell completions are one line, for example source <(amp completions zsh) (bash and pwsh work too, and fish uses amp completions fish | source).

Step 2: log in

amp login

amp login opens the browser and adds an account. The CLI can keep several: amp account list shows them, amp account switch <email-or-user-id> picks the one future commands use, and amp logout removes the active one (--all removes them all).

For scripts, CI and machines without a browser, use an access token instead:

export AMP_API_KEY=sgamp_your-token-here

Create the token in Settings on ampcode.com; it starts with sgamp_. The session token that amp login stores expires within an hour and can’t be refreshed, so the CLI rejects it there.

Two optional links change who pays for model usage:

• ChatGPT subscription: amp config model-providers add-chatgpt-subscription (or the short amp add-chatgpt-sub) links a ChatGPT plan, so OpenAI model usage counts against it.
• Claude subscription: works only in Amp’s Claude Code mode, which you pick on the Dial. Amp’s own modes never run off your Claude plan.

Step 3: CLI basics

Run amp in a project and type. Piped input becomes the first message, so echo "commit all my changes" | amp works too. The shortcut you’ll use most is Ctrl+O, which opens the command palette.

If you type while Amp is working, Enter steers it: your message arrives after the current step instead of waiting for the whole turn. To queue a message until the agent finishes, run prompt: queue message from the palette. Shift+Enter adds a newline in terminals that support it; Ctrl+J works everywhere. Inside tmux, run tmux set -s extended-keys on so Shift+Enter works.

From the palette, ide connect links Amp to VS Code, Cursor, Windsurf, Zed or Neovim (Neovim needs a plugin). amp config keymap prints every shortcut.

Step 4: pick a mode on the Dial

Amp doesn’t ask you for a model. It asks for a mode, and each mode is a combination of model, reasoning effort, system prompt and tools tuned for a level of difficulty:

Press Ctrl+S before your first message to turn the Dial, or open the palette and type mode. A thread keeps the mode it started with, so if you picked the wrong one, start a new thread rather than fighting it. Starting too high wastes time and credits on a simple change; starting too low can cost more if you need several attempts.

If you want control over the models, Settings → Mode Dial → Tune Modes lets you pin models per mode, and you can bring your own API keys. If you’d rather choose an exact model for every session, a multi-provider agent like opencode fits that habit better.

Step 5: subagents, the oracle and the librarian

Amp can hand focused work to subagents, each with its own context window:

• Task does delegated work end to end and reports back. It can edit files and run commands, and it has read-only skills for searching your code, researching another repository, reviewing a change and planning.
• Read Thread reads and summarizes other Amp threads.

Both run the same model as the thread that started them. Amp picks them on its own for suitable work, mostly in medium mode, and you can ask for them directly: “split this across subagents”.

The oracle (a reviewer that never edits files), the librarian (which clones other repositories into /tmp and explains them) and the finder (fast code search) are now part of Task. To run them as separate tools on a model you choose, install them as plugins:

amp plugins add @amp/oracle
amp plugins add @amp/librarian
amp plugins add @amp/finder

Step 6: settings

Amp reads two settings files, and workspace values win:

• User: ~/.config/amp/settings.json (or .jsonc).
• Workspace: .amp/settings.json in the project.

amp config edit opens the user file and amp config edit --workspace opens the project one. Every key starts with amp.:

{
  "$schema": "https://ampcode.com/cli-settings.schema.json",
  "amp.showCosts": true,
  "amp.git.commit.coauthor.enabled": true,
  "amp.notifications.enabled": true
}

• amp.showCosts shows what each thread costs.
• amp.tools.disable turns off tools by name, with * globs; amp tools list lists the built-in ones.
• amp.git.commit.ampThread.enabled and amp.git.commit.coauthor.enabled control what Amp adds to its commit messages, such as the Amp-Thread-ID trailer that links a commit to its thread.

One thing to know before you start: by default Amp doesn’t ask for approval before running tools. Work on a branch, commit often, and use amp.tools.disable or a plugin if you want limits. If you want an agent that asks first by default, Claude Code and Codex CLI are built around approval prompts.

Skills work the way you may know from other agents: a folder with a SKILL.md. Amp loads project skills from .agents/skills/, personal ones from ~/.config/amp/skills/ and ~/.config/agents/skills/, and also the Claude Code folders .claude/skills/ and ~/.claude/skills/.

Step 7: AGENTS.md

AGENTS.md holds the rules for a project: how to build, test and lint, which conventions to follow, which folders to leave alone. Amp reads the one in the current folder and every parent folder up to your home folder, and always includes them. An AGENTS.md in a subfolder is added when Amp reads a file there. If a project has none, Amp offers to write one.

# Project rules

- Package manager: pnpm. Run `pnpm test` before you finish a task.
- TypeScript strict mode; no `any` in new code.
- API handlers live in src/api/; one file per route.
- See @docs/architecture.md for the module layout.

A few details worth knowing:

• @-mentions pull in other files: relative paths, @~/ paths and globs like @docs/*.md.
• Personal rules go in ~/.config/amp/AGENTS.md (or ~/.config/AGENTS.md).
• Fallback: in a folder without AGENTS.md, Amp reads AGENT.md or CLAUDE.md, so a Claude Code project works on day one.
• Scoped rules: a mentioned file can carry globs: front matter, so its guidance applies only when Amp works on matching files.

What to put in the file is covered in how to write CLAUDE.md and AGENTS.md.

Step 8: MCP servers

MCP servers give Amp new tools: a browser, an issue tracker, docs search. The quickest way to add one is the CLI:

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

Both end up under amp.mcpServers in your settings. A local server is a command, a remote one is a URL, and ${VAR} pulls values from the environment:

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

Servers in a workspace’s .amp/settings.json don’t run until you approve them with amp mcp approve <name>; amp mcp doctor shows the state of each server. When the same server is defined in several places, --mcp-config wins over the workspace file, which wins over your user settings. Because every server adds its tools to the context, the docs suggest bundling rarely used servers inside a skill (with an mcp.json) so their tools load only when the skill does.

Step 9: threads and execute mode

Every thread has a URL like https://ampcode.com/threads/T-…. amp threads continue T-… picks one up in the terminal, amp threads share T-… --visibility unlisted makes it shareable, and typing @T-… in a prompt pulls another thread in as context. Threads you start outside a workspace are private.

For scripts and CI, execute mode runs one prompt and exits:

amp -x "what package manager is used here?"
git diff | amp -x "review this diff for bugs"
amp -ox "Investigate why the latest CI run on main failed"

-x runs on your machine and turns on by itself when output is redirected. -ox runs the prompt on an orb instead. --stream-json prints machine-readable output, and --mcp-config adds MCP servers for that one run.

What Amp costs (as of October 2026)

Model usage comes from one of three places: a ChatGPT or Claude subscription you’ve linked, your own API keys, or Amp credits. When you run out of included usage you add credits, and Amp charges them at the actual model and tool cost of each thread, with no markup on provider API prices for individuals and non-enterprise workspaces. You don’t need a paid tier to buy credits. Web search uses credits too. Credits expire twelve months after purchase, and amp usage shows your balance. Orbs are billed by the minute and pause when idle; runners on your own machine are free.

Common pitfalls

• Wrong mode, and Ctrl+S won’t change it. The thread already has a first message. Start a new one with Ctrl+C Ctrl+N.
• CI says your login is invalid. The amp login session token is short-lived. Set AMP_API_KEY to an sgamp_ access token.
• A workspace MCP server never shows up. It needs approval: amp mcp approve <name>, then check with amp mcp doctor.
• Your Claude plan isn’t being used. Only the Claude Code mode runs on it; low to ultra use Amp’s own routing.
• Amp ran a command you didn’t expect. It doesn’t ask by default. Disable the tool or work on a branch you can throw away.
• Shift+Enter sends the prompt in tmux. Turn on extended-keys, or use Ctrl+J.

Running Amp next to other CLIs in AgentVera

Amp has its own web app, desktop app and orbs, and if Amp is the only agent you use, those may be all you need. It gets harder when Amp runs next to Claude Code, Codex or Gemini CLI on the same project. AgentVera is a desktop app that runs these CLIs side by side in real terminals, with your own installs and logins. Amp support works like this:

• Your Amp login. Amp uses its own ampcode.com login. If you’re signed out, the agent’s terminal asks you to sign in on first launch. Under Settings → Accounts → Accounts of other agents you can add more Amp accounts, which run on API keys, and give each agent an ordered list of fallback accounts.
• One thread per agent. A new thread is created for each agent ahead of time with amp threads new, and the agent returns to it with threads continue on later launches.
• Modes, not models. You pick low, medium, high or ultra for each agent, passed with --mode.
• MCP and the browser. The servers you add in AgentVera’s MCP manager and AgentVera’s browser are passed with --mcp-config. Amp has no extra-instructions flag, so the agent’s role field isn’t used; your AGENTS.md applies instead.
• Panes, worktrees, review and flows. Run Amp in the workspace grid next to other agents, each in its own git worktree so they don’t overwrite each other. Automatic code review checks their changes, and in flows (Pro and Team) Amp can be the source or the target agent.

The grid, worktrees, code review and the MCP manager are on the free plan. To try it, download AgentVera.

Wrapping up

To use Amp, install the CLI, run amp login, pick a mode with Ctrl+S, and describe the task. Start most threads on medium, move to high or ultra for the hard ones, and let subagents take the searching and reviewing. Put project rules in AGENTS.md, tools in amp.mcpServers, and use AMP_API_KEY with amp -x for scripts. Because Amp runs tools without asking, keep it on a branch, and you’ll get the most out of an agent that is built to just get on with the work.