Mercury CLI
Documentation

Start

Overview

Mercury CLI (mercury-cli.ai, npm package mercury-tech-cli) is a terminal AI coding agent for software repositories on macOS, Linux and Windows. You tell it what you want: the agent reads your codebase, edits files, runs builds and tests, steps through failures in a real debugger, and shows every step as it happens. You can run several sessions in parallel, each on the model provider you choose, and any session can dispatch crewmates in isolated git worktree checkouts on other providers' models.

A session keeps its conversation, model, permissions, workspace and running work across screen changes. Opening another session leaves the first one running.

What you can do

  • Work on several things at once. Open a second session and the first keeps going. A board shows what every one of them is doing, and a parked chat picks up where it stopped.
  • Choose the provider per session. Sign in once per company and stay signed in to all of them: OpenAI, Anthropic, Google, DeepSeek, Moonshot, Z.AI, OpenRouter, Hugging Face, xAI, Meta, Mistral, Nous Portal, OpenCode Zen, Qwen, MiniMax, Together AI, Cohere, Groq, Cerebras, Fireworks AI, Melious AI and OrcaRouter, or a model running on your own machine or a rented GPU. Switch mid-work without leaving the chat.
  • Work with a crew. Every session has a crew from the start. Launch crewmates with a name, folder and chosen model, give them separate git worktrees when needed, message them by name, and follow their work from the Crew view.
  • Decide how much it may do alone. The modes run from asking before every edit to working unattended, and one keystroke moves between them. Mercury also asks before anything a repository's own configuration wants to run.
  • Real tools. The agent uses a language server for definitions, references and refactors, a real debugger with breakpoints, a test runner that drops a failing test straight into the debugger, and a search that matches code by its shape.
  • Read and write documents. Read opens PDFs, office documents and scanned pages as text on every model, Grep searches them, and a fetched PDF comes back with its first page (Reading documents). The Document tool creates, converts and inspects local documents (Documents, spreadsheets and references).
  • Train a model on your sessions. mercury tune turns your project's sessions into a training book, can add reasoning to its assistant turns, trains a LoRA adapter on a rented GPU, and installs the merged model into your Bank for /localsetup (Train a model on your sessions).
  • See the screen, hear your voice. With the desktop driver present, the model can see your screen and work the application in front of you, asking before its first move in each one. Dictate a prompt on-device with Whisper (/voice on), generate local images and video on your own computer with /imagesetup (Local images and video), or generate videos from prompts and project references with the Video tool (Video).
  • Come back later. Wake a session with a prompt at a set time or on a schedule. Every project keeps a memory that outlives any one conversation: what you ask it to remember goes into topic pages, your pinned rules and branch-relevant facts open every chat, and hybrid Recall retrieval (local on-device semantic embeddings, word matching and citation tracking) finds relevant records as you work.
  • A second opinion while it works. Turn on the advisor with /advise and a second model of your choice reads the conversation on a cadence and leaves the working model a short note. Every model can search the web without an API key, through the provider's own search or Mercury's built-in coding sources.
  • Start from a specification. In Apollo Mode the agent interviews you until the specification exists, writes it down and builds a prototype from it in one run.
  • Extend it. Extensions add commands, agents, hooks and servers from a git URL, a folder or an archive, with approval tied to what each one contributes, and /extensions includes bundled FilmCraft (0.12.0), PhotoCraft (0.14.0) and LightCraft (0.13.0) extensions with a shared installer and MCP bootstrap (Extensions), plus the bundled mercury-media (0.1.0) extension for local image and video generation (Local images and video). MCPs & Skills chooses per repository what a session loads, with named presets.
  • Know the install is sound. The health check checks the runtime, settings and release channel in one verdict, with details behind each row and fixes it can apply.
  • Use it where you work. A full-screen terminal app, inside VS Code or any editor that speaks the Agent Client Protocol, headless in a script or driven from a program through the TypeScript and Python SDK (mercury-cli-sdk) or over mercury run --format rows and mercury runner (Automation), or on a timer. For people who make games, bridges into a running Unity, Blender or Godot editor and a batch bridge into Aseprite.

mercury mcp-server lets another agent submit outside reports, read session rows and search project memory (Mercury as an MCP server).

The screens

  • The home screen is where Mercury opens, with rows for starting or continuing a session, opening the Boot Menu, MCPs & Skills, Agents, Health Check, Saturn Scheduler and Logins, and opening the Session Concourse or the combined Sessions · Projects picker.
  • The chat is the session you are looking at. Every tool call shows as it runs, collapsed to a card or opened to its full output.
  • The board (the Session Concourse) lists the project's sessions, running ones above parked chats, each row saying what its session is doing right now. Shift+→ from the home screen opens it, and /concourse from a chat does the same.
  • The strip is the row of open screens. Shift+← and Shift+→ move between them, and the chat joins the strip once a session is focused.

See Using Mercury for the home-screen rows, starting a session and switching between sessions on the board.

Install and providers

The release archives carry their own Node runtime (24.22.1) and ripgrep, so a fresh machine needs only git. One command per platform is on the Install and update page, and Quickstart walks through the first run. Mercury CLI, the TypeScript and Python SDKs in sdk/ and sdk-py/ (mercury-cli-sdk on npm and PyPI), and the VS Code extension are open source under the Apache License 2.0 (Apache-2.0, LICENSE.md and NOTICE).

  • Provider accounts. /logins opens the sign-in catalogue, the same card the first run shows, and /accounts manages connected accounts and API keys afterwards.
  • Your own machine and rented GPUs. Open /llmhost to search the 78 shipped recipes across 32 models or any public Hugging Face text-generation model, load a custom recipes JSON file through Private recipes, bank weights locally or mirror kept Runpod and Vast.ai volumes in Bank · your weights, choose your Weights source (Hugging Face, Private repository, This computer's Bank or Kept volume), and run a model on a GPU rented from Runpod, Vast.ai, Lambda, Hugging Face, Hyperstack, Verda or DigitalOcean, on your own computer or a saved SSH computer (mercury host), or on a model server already running, with quality, conversations × context, thinking and WEIGHTS shown, or run /localsetup to pull a GGUF from Hugging Face into the Bank, start one from the Bank on llama-server, or set up Ollama and connect to running servers. A local model server or a keyless custom endpoint needs no sign-in.
  • Models and effort. /model and /effort change the session's model and effort level and save the pick as the default for new sessions; see Providers and sign-in for default model selection and /llmhost hosting.
  • Workspace trust. Before running any hook, helper or server from a repository's own configuration, Mercury asks whether you trust the repository; see Workspace trust and permissions.

Quickstart · Using Mercury · Sessions · Providers and sign-in · Models and effort · Permission modes · Install and update · Local images and video · SDK · Automation