An agent reads and edits files, runs shell commands, steps through tests and debuggers, and checks the results while you choose the model provider, the model, and what the agent is allowed to do. Mercury is used to build Mercury across parallel sessions and models: each session writes a handoff note when it finishes, and the next session reads that note once at startup alongside your pinned rules, stopping context poisoning between sessions.

Mercury is open source under the Apache License 2.0, as are the SDKs in [sdk/](sdk/) and [sdk-py/](sdk-py/).
## Install
Release archives for Apple silicon and Intel Macs, Linux x64 and arm64, and Windows x64 and arm64 include Node and ripgrep (`git` is the only separate requirement):
```sh
curl -fsSL https://mercury-cli.ai/install | sh # macOS and Linux (x64 and arm64)
irm https://mercury-cli.ai/install.ps1 | iex # Windows (x64 and arm64), in PowerShell 7
brew install Whq02/mercury/mercury # Homebrew: macOS and Linux x64
npm install -g mercury-tech-cli # npm; `bun install -g mercury-tech-cli` is the same package
mise use -g npm:mercury-tech-cli # mise, through the npm package
```
To run a Windows archive without installing it, extract it and run `mercury\mercury.exe` from PowerShell or Command Prompt. `mercury.cmd` and `mercury.ps1` are also in that folder.
The install addresses keep approximate script-request counts by source and UTC day (completed installs are not counted); the counter stores no IP address, user-agent string or cookie. Open a new terminal (or run the `export PATH=…` line the shell installer prints), check `mercury --version`, and run `mercury` inside a repository. See [docs/INSTALL.md](docs/INSTALL.md), [docs/INSTALL-WINDOWS-FROM-SOURCE.md](docs/INSTALL-WINDOWS-FROM-SOURCE.md) and [AGENTS.md](AGENTS.md) for `mercury update`, release verification, requirements and building from source.
## What is inside
- **22 model providers, `/llmhost` and `/localsetup`:** keep all 22 providers signed in at once (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, OrcaRouter, or your own local/hosted weights) and switch models mid-chat; new sessions default to your most recently connected provider. Rent or host weights with `/llmhost` and `mercury host` ([docs/LLM-HOST.md](docs/LLM-HOST.md)), run a local model on TensorFold with `/tensorfold` ([docs/TENSORFOLD.md](docs/TENSORFOLD.md)), connect Ollama, LM Studio, vLLM or llama.cpp with `/localsetup` ([docs/LOCAL-SETUP.md](docs/LOCAL-SETUP.md)), and see [docs/ENGINES.md](docs/ENGINES.md) for sign-ins and routing.
- **The daily loop, Session Concourse and crewmates:** interactive launches open the home screen (New Session, Continue Last Session once session history exists, Boot Menu, MCPs & Skills, Agents, Health Check, Saturn Scheduler, Logins, Session Concourse, Sessions · Projects); run parallel sessions on `/concourse` and delegate to cross-provider crewmates (`Crewmate`) in isolated `git worktree` checkouts with project file leases ([docs/SESSIONS.md](docs/SESSIONS.md), [docs/CREW.md](docs/CREW.md)).
- **Headless CLI and JSON-RPC runner:** run one-shot prompts with `mercury run ""` (`--format text|json|rows`, `--input rows`, `--partial`), or host multi-turn sessions over stdio with `mercury runner` and the TypeScript and Python SDKs ([docs/AUTOMATION.md](docs/AUTOMATION.md), [sdk/](sdk/), [sdk-py/](sdk-py/)).
- **Mneme hybrid RAG project memory:** on-device 118 MB BGE semantic embeddings (`bge-base-en-v1.5`, bundled in every release archive, built for its platform) fused with BM25 word ranking, citation tracking, verbatim pinned rules, contradiction checks, session handoff notes, and the `/memory page` browser graph ([docs/MNEME.md](docs/MNEME.md), [docs/MEMORY-FINDINGS.md](docs/MEMORY-FINDINGS.md)).
- **LSP, 57-language AST, DAP debugger and `Eval` cells:** anchored multi-file edits ([docs/CHANGE-TRANSACTIONS.md](docs/CHANGE-TRANSACTIONS.md)), LSP navigation and previewed refactors ([docs/LANGUAGE-SERVICE.md](docs/LANGUAGE-SERVICE.md)), 57-language tree-sitter search and rewrites ([docs/STRUCTURAL-PATTERNS.md](docs/STRUCTURAL-PATTERNS.md)), Debug Adapter Protocol stepping for failing Python, JS/TS, Go and Rust tests ([docs/DEBUGGER.md](docs/DEBUGGER.md)), and persistent Python and JavaScript code cells with browser samples ([docs/EVAL.md](docs/EVAL.md), [docs/SAMPLES.md](docs/SAMPLES.md)).
- **Keyless `WebSearch` and markdown `WebFetch`:** cascades through provider-native search, Brave or Tavily keys, official APIs (Stack Exchange, npm, PyPI, crates.io, GitHub, Hacker News, Wikipedia), SearXNG and keyless DuckDuckGo, and reads public pages as markdown within a 38,000-character call budget ([docs/ENGINES.md](docs/ENGINES.md)).
- **Computer use, Whisper voice, Saturn, video and editor bridges:** desktop control with `Computer` ([docs/COMPUTER-USE.md](docs/COMPUTER-USE.md)), on-device Whisper dictation with `/voice` ([docs/VOICE.md](docs/VOICE.md)), recurring or one-shot schedules with `/saturn` ([docs/SATURN.md](docs/SATURN.md)), MiniMax video generation ([docs/VIDEO.md](docs/VIDEO.md)), and bridges for VS Code (`mercury acp`), [Unity](docs/UNITY-BRIDGE.md), [Blender](docs/BLENDER-BRIDGE.md), [Godot](docs/VULCAN-GODOT-TOOLS.md) and [Aseprite](docs/ASEPRITE-BRIDGE.md).
See [docs/README.md](docs/README.md) for the full documentation catalogue ([docs/TRUST.md](docs/TRUST.md), [docs/KIT.md](docs/KIT.md), [docs/EXTENSIONS.md](docs/EXTENSIONS.md), [docs/HEALTH-CERTIFICATE.md](docs/HEALTH-CERTIFICATE.md), [docs/APOLLO-MODE.md](docs/APOLLO-MODE.md), [docs/DURABILITY.md](docs/DURABILITY.md), [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md)).
## Slash commands
`/help` lists the available interactive commands and `/palette` searches them (`MERCURY_SAMPLES=1` adds `/samples` under `current work`):
| Domain | Commands |
| --- | --- |
| current work | `/run` `/runs` `/workbench` `/diff` `/mission` (/goal) |
| crew & delegation | `/agents` `/crewmates` `/crew` `/swarm` `/swarmchat` `/general` `/team` `/whisper` `/daemon` `/saturn` `/seats` `/kill` `/unkill` |
| session & context | `/clear` `/compact` `/context` `/rewind` `/sessions` `/concourse` `/rename` `/title` `/contract` `/export` `/copy` `/usage` `/realms` `/restart` |
| memory & goals | `/memory` `/console` |
| model & effort | `/model` `/effort` `/submodels` `/advise` `/caching` `/tensorfold` |
| git & review | `/review` `/audit` |
| health & introspection | `/health` `/verify` `/trace` `/capabilities` `/lsp` |
| config & setup | `/config` `/jev` `/localsetup` `/llmhost` `/imagesetup` `/permissions` `/hooks` `/mcp` `/extensions` `/skills` `/browser` `/orient` `/keybindings` `/keys` `/vim` `/mouse` `/keysetup` `/bootmenu` `/voice` |
| appearance & cockpit | `/appearance` `/critter` `/palette` `/zen` `/browse` |
| account & app | `/logins` `/logout` `/accounts` `/defaultprovider` `/update-notes` `/feedback` `/help` `/exit` |
| Command | What it does |
| --- | --- |
| `/imagesetup` | Set up local image and video models. |
| `/llmhost` | Choose a model to rent on Runpod, Vast.ai, Lambda, Hugging Face Inference Endpoints, Hyperstack, Verda or DigitalOcean, run on your own computer, or connect an existing server. |
| `/tensorfold` | Run a local model on TensorFold: install the engine, pull a model, serve it on this Mac, share it on your network or rent a GPU for it, and switch to it, all on one screen. |
| `/restart` | Move this chat to the installed Mercury build; running watches and background shells stop. |
| `/mcp` | Inspect servers, sign in, browse each server’s tools and parameters, reconnect, or toggle a server for this chat. |
## Author
Mercury CLI is designed, built and maintained by **Waleed Al Qusous** as its sole developer: seven months from the first line to this release, 56 public releases, 586,000 lines of TypeScript and 4,700 proofs, built with the AI agents it now runs. [GitHub](https://github.com/Whq02) · [X](https://x.com/dubsthedev) · [mercury-cli.ai](https://mercury-cli.ai)
## Reporting a problem
For a short report (OS, what you tried, what broke; no health dump), use [the tester form](https://mercury-cli.ai/report) or `/bug --short ` inside Mercury. Run `/bug ` to preview and file a full report through your signed-in GitHub CLI (`gh`), or open an issue with your `--version` output, OS, terminal, steps and `mercury health --json` (`node dist/mercury.mjs health --json` for a source build). Report security problems privately through the repository's Security tab ([SECURITY.md](SECURITY.md)); see [CONTRIBUTING.md](CONTRIBUTING.md) for pull requests and checks.
## Licence
The Mercury CLI is licensed under the Apache License 2.0 (`Apache-2.0`); see
[LICENSE.md](LICENSE.md). The TypeScript and Python SDKs use the same licence
([sdk/LICENSE](sdk/LICENSE) and [sdk-py/LICENSE](sdk-py/LICENSE)).
The [trademark policy](TRADEMARKS.md) covers use of the Mercury name and marks.
Bundled third-party licences are listed in
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).