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

URL: https://agentvera.dev/en/blog/how-to-use-amp/ · Published: 2026-10-29

How to use Amp, the coding agent: install the CLI, log in, pick a mode on the Dial, and set up AGENTS.md, MCP servers, subagents and credits.

**In short:**

- Install the Amp CLI with one curl command (macOS, Linux, Windows through WSL), run amp login, then run amp in a project and describe the task. Every conversation is a thread saved on ampcode.com.
- Instead of a model you pick a mode on the Dial: low, medium, high or ultra. Choose it with Ctrl+S before the first message, because a thread keeps its mode.
- Project rules go in AGENTS.md, settings and MCP servers in ~/.config/amp/settings.json or .amp/settings.json. The Hobby tier is free; model usage comes from your subscriptions, your keys or credits.

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](/en/glossary/coding-agent/ "What 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

| Platform | Command |
| --- | --- |
| macOS, Linux | `curl -fsSL https://ampcode.com/install.sh \| bash` |
| Windows | Run the same command inside WSL |

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

```bash
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:

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

| Shortcut | What it does |
| --- | --- |
| `Ctrl+O` | Opens the command palette |
| `Ctrl+S` | Turns the Dial (before the first message) |
| `@` | Mentions a file |
| `Ctrl+V` | Pastes an image, even on macOS |
| `Ctrl+G` | Writes the prompt in `$EDITOR` |
| `Ctrl+R` | Opens your prompt history |
| `Esc Esc` | Interrupts the agent |
| `Ctrl+C Ctrl+N` | Archives the thread and starts a new one |
| `Ctrl+C Ctrl+C` | Quits |

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:

| Mode | Use it for |
| --- | --- |
| `low` | Small, well-defined changes |
| `medium` | Most work; the docs’ default advice |
| `high` | Hard or subtle problems |
| `ultra` | Open-ended work like migrations and architecture |

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](/en/glossary/subagent/ "What is a subagent"), 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:

```bash
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.`:

```json
{
  "$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.

```markdown
# 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](/en/blog/claude-md-agents-md/ "How to write CLAUDE.md and AGENTS.md").

## Step 8: MCP servers

[MCP servers](/en/blog/what-is-mcp-server/ "What is an MCP server") give Amp new tools: a browser, an issue tracker, docs search. The quickest way to add one is the CLI:

```bash
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:

```json
{
  "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:

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

| Tier | Price | What you get |
| --- | --- | --- |
| Hobby | Free | Every product feature; pay-as-you-go orbs; use your subscriptions or keys |
| Individual (Megawatt) | $20 a month | Included usage plus 45,000 minutes of Amp-hosted orb time |
| Teams | No extra charge | Shared threads, skills and billing, pooled credits, SSO |
| Enterprise | Custom | Admin controls, audit logs, data retention options |

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](/en/agents/amp/ "Amp in AgentVera") 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](/en/features/mcp-manager/ "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](/en/features/workspace/ "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](/en/download/ "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.

## Frequently asked questions

**Is Amp free?** As of October 2026 the Hobby tier is free and has every product feature. You pay for model usage through a ChatGPT or Claude subscription you link, your own API keys, or Amp credits, which Amp charges at the providers’ API prices without a markup for individuals. The Individual tier costs $20 a month and adds 45,000 minutes of Amp-hosted orb time.

**Who makes Amp now?** Amp began inside Sourcegraph. In December 2025 it spun out as its own independent company, and the CLI, the web app and the docs now live at ampcode.com.

**Can I choose the model in Amp?** Not directly per message. You pick a mode (low, medium, high or ultra) and the mode decides the model, reasoning effort, prompt and tools. You can pin models for a mode in Settings → Mode Dial → Tune Modes, and bring your own API keys.

**Does Amp read CLAUDE.md?** Yes, as a fallback. In any folder without an AGENTS.md, Amp reads AGENT.md or CLAUDE.md instead. It also loads skills from the Claude Code skill folders, .claude/skills/ and ~/.claude/skills/, unless you turn that off.

**Does Amp ask before running commands?** No. By default Amp does not ask for approval before running tools. You can turn off built-in tools with amp.tools.disable, set rules for MCP tools with amp.mcpPermissions, or write a plugin that decides which tool calls run.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/