Mermaid
An open-source AI coding assistant for the terminal. Multi-provider — Ollama (local), Anthropic, Gemini, Meta, OpenAI, Groq, OpenRouter, and any OpenAI-compatible endpoint — with native tool calling, subagents, computer use, and a clean TUI.
Features
- Native tool calling — read, write, edit, delete, run commands, search the web, spawn subagents, call MCP tools
- Computer use — screenshot, click, type, press keys, scroll, move the mouse, list windows
- Subagents — spawn parallel autonomous agents; built-in
general and read-only explore types, per-call model override, continuation handles
- Worktree isolation — give a writing subagent its own git checkout, seeded with your uncommitted state. Its changes land as one patch, serialized against other children, so parallel writers report a conflict instead of interleaving
- Safety modes —
plan/read_only/ask/auto/full_access, cycled live with Shift+Tab; auto is classifier-backed, and gated actions prompt inline rather than erroring out
- Plan mode — a hard read-only state where the agent explores and authors a plan file you approve before anything changes;
mermaid run --plan does it headless
- Checkpoints — shadow-git snapshots before mutations; inspect with
/checkpoints, roll back with /restore
- Durable memory — the agent remembers facts across sessions; a compact index auto-loads into every prompt
- Project instructions and skills — auto-loads
AGENTS.md and MERMAID.md, plus task-specific playbooks loaded on demand
- MCP servers — stdio JSON-RPC client with a built-in registry of 16 popular servers
- Sessions — conversations auto-save;
--continue reopens the last one here, --resume opens a picker, double-Esc forks the timeline at an earlier message
- Context compaction — automatic checkpoint-and-continue when the window fills; manual
/compact [focus]
- Image paste — Ctrl+V attaches images for vision models on X11, Wayland, macOS, and Windows
- Reasoning levels — seven tiers, cycled with Alt+T, persisted per model
- Record and replay —
--record captures every reducer input; --replay reconstructs the session offline, deterministically
- Non-interactive mode — script with
mermaid run "prompt" for CI and automation
Install
No Rust or cargo required — the installer downloads a prebuilt binary for your platform from the latest GitHub Release, verifies its checksum, and puts mermaid on your PATH.
macOS / Linux
curl -fsSL https://noahsabaj.github.io/mermaid-cli/install.sh | sh
Windows (PowerShell)
irm https://noahsabaj.github.io/mermaid-cli/install.ps1 | iex
Run mermaid to start, mermaid update for the newest version. (MERMAID_INSTALL_DIR changes the location; MERMAID_VERSION=vX.Y.Z pins a release.)
Or install with a package manager
# Homebrew (macOS / Linux)
brew install noahsabaj/mermaid/mermaid
# Scoop (Windows)
scoop bucket add mermaid https://github.com/noahsabaj/scoop-mermaid
scoop install mermaid
# WinGet (Windows) — pending review on the official winget-pkgs repo
winget install NoahSabaj.Mermaid
All three are bumped on every release.
With the Rust toolchain, cargo install mermaid-cli works too, though crates.io can lag the newest tag. Every release also attaches prebuilt binaries and Linux .deb/.rpm packages.
Mermaid needs one model backend, either kind. Ollama covers local inference (models auto-pull) but is not required — a provider API key alone is enough, see Remote providers. Name a remote model once with mermaid --model anthropic/ and Mermaid remembers it.
First 10 minutes
mermaid doctor # Check model, tools, safety, and project instructions
mermaid # Start the full-screen terminal coding agent
Then ask for normal coding-agent work:
- "read the repo and tell me where the test runner lives"
- "find the bug in this failing test and fix it"
- "review the current branch for regressions"
Inside the TUI, use /help for grouped commands, /doctor for the session readiness report, /context to inspect prompt budget, /compact [focus] to create a handoff checkpoint, and Esc to interrupt the agent loop.
Usage
mermaid # Start fresh session
mermaid --continue # Resume the most recent session in this directory
mermaid --resume # Pick a past session from a searchable list
mermaid --model anthropic/ # Pick a model (see Remote providers below)
mermaid --reasoning high # Override default reasoning depth
mermaid --path /path/to/project # Run against a specific project directory
mermaid list # List available models across providers
mermaid doctor # First-run readiness check
mermaid init # Create default config file
mermaid add # Add an MCP server (e.g., context7, git)
mermaid pr create # Open a PR/MR from the current branch (wraps gh/glab)
mermaid run "fix the tests" # Non-interactive mode
mermaid run "explain main.rs" -f json # JSON output (or -f ndjson to stream events)
mermaid run --plan "refactor the auth" # Headless plan mode: read-only, delivers a plan file
mermaid --sandbox run "refactor this" # Confine writes to the project, deny network
Every flag, structured output, headless session resume, and record/replay: docs/cli-reference.md.
mermaid add resolves the name through a registry of 16 popular MCP servers (context7, playwright, git, postgres, notion, slack, and more), prompts for required env vars, and validates by spawning the server.
Keyboard shortcuts
| Key | Action |
|---|
| Enter | Send message (or queue while the model is generating) |
| Esc | Stop generation / dismiss palette |
| Esc Esc | (idle) Rewind: fork the session at an earlier message |
| Ctrl+C | Quit (auto-saves the session) |
| Alt+T | Cycle reasoning level |
| Shift+Tab | Cycle safety mode: plan → read_only → ask → auto → full_access |
| Ctrl+V | Paste image or text from clipboard |
| Ctrl+O | Compose the prompt in $VISUAL/$EDITOR |
/ | Open the slash-command palette |
@ | Open the fuzzy file picker |
The full tables add selection, background processes, and every slash command; /help groups them in the TUI.
Tools
The model calls these autonomously:
| Tool | Description |
|---|
read_file | Read files (text, PDF, images) |
write_file | Create or overwrite files (timestamped backup) |
apply_patch | Multi-hunk, context-anchored edits with a diff (fuzzy-tolerant) |
delete_file | Delete files (timestamped backup) |
create_directory | Create directories |
execute_command | Run shell commands; background mode tracks PID, log, and URL |
memory | Durable cross-session memory (project, shared, or global scope) |
web_search | Search the web (managed local SearXNG by default) |
web_fetch | Fetch a URL into a bounded session snapshot (in-process, no key) |
agent | Spawn an autonomous subagent for parallel tasks |
Plus seven computer-use tools — screenshot, list_windows, click, type_text, press_key, scroll, mouse_move — advertised only in interactive sessions with a usable GUI backend. Linux/X11 and Linux/Wayland are full-control; macOS does screenshots and clipboard paste but not click/type/scroll; Windows is not wired yet. Helpers and the full matrix: docs/tools.md.
MCP servers contribute tools under the mcp____ prefix, deferred by default: one tool_search tool promotes matches for the rest of the session, so unpromoted schemas never count against /context. Opt out with mcp_defer_tools = false.
Safety
Approval policy and OS confinement are independent. The policy (plan, read_only, ask, auto, full_access) decides what needs your say-so; the sandbox decides what the kernel permits regardless:
--no-network — blocks web tools everywhere, and stops model-run commands from reaching the network--confine-fs — write-class filesystem access only beneath the project root, cwd, and temp--sandbox — both at once
Enforcement is seccomp-BPF plus Landlock on Linux, Seatbelt on macOS, AppContainer plus Job Objects on Windows. It fails closed: unappliable confinement exits 126 rather than running unconfined. See docs/sandbox.md.
Project instructions
Create an AGENTS.md (the cross-tool open standard) and/or a MERMAID.md (mermaid-specific) at your project root with conventions, tool versions, naming patterns, and run commands. Both load from the nearest matching directory — AGENTS.md first, then MERMAID.md, so MERMAID.md overrides on conflict. They auto-reload when the files change, and the walk stops at the .git root or $HOME. This repo's own AGENTS.md is a worked example.
Configuration
Config lives at ~/.config/mermaid/config.toml; mermaid init creates one. A repo can commit shared defaults in .mermaid/config.toml, which can tighten safety but never loosen it. Layers merge key-by-key, later winning: built-in defaults, user config, project config, then session flags (-c key.path=value).
[default_model]
provider = "ollama"
name = "qwen3-coder:30b"
reasoning = "medium" # none | minimal | low | medium | high | xhigh | max
[safety]
mode = "ask" # plan | read_only | ask | auto | full_access
checkpoint_on_mutation = true
The annotated full schema — safety enforcement floors, compaction budgets, subagent types, profiles, model aliases, provider overrides, web backends — is in docs/configuration.md.
Remote providers
Set the appropriate environment variable, or override it with [providers.].api_key_env. Model names are whatever the vendor currently ships; Mermaid passes them through.
| Provider | Env var | Model format |
|---|
| Anthropic | ANTHROPIC_API_KEY | anthropic/ |
| Google Gemini | GOOGLE_API_KEY (GEMINI_API_KEY legacy fallback) | gemini/ |
| Meta | MODEL_API_KEY | meta/ |
| OpenAI | OPENAI_API_KEY | openai/ |
| Groq | GROQ_API_KEY | groq/ |
| OpenRouter | OPENROUTER_API_KEY | openrouter// |
| Cerebras | CEREBRAS_API_KEY | cerebras/ |
| DeepInfra | DEEPINFRA_API_KEY | deepinfra// |
| Together | TOGETHER_API_KEY | together// |
| NVIDIA NIM | NVIDIA_API_KEY | nvidia// |
| Cloudflare Workers AI | CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID | cloudflare/@cf// |
| Grok (xAI) | XAI_API_KEY | grok/ (xai/ alias) |
| Ollama Cloud | OLLAMA_API_KEY | ollama/:cloud |
Environment variables always win; the OS keyring fills the gap when none is set. Store a key with mermaid login and remove it with mermaid logout . Keys are reported as env, keyring, or none — never by value. Per-provider details are in docs/configuration.md.
Architecture
Mermaid's runtime is an Elm/MVU pattern: one pure reducer (fn update(State, Msg) -> (State, Vec)), effects as data, structured concurrency per turn. Duplicate error display, 20-press Ctrl+C during tool execution, stale stream events corrupting a new turn — whole classes of bug are statically impossible against those types.
Documentation
- docs/cli-reference.md — every flag, shortcut, and slash command
- docs/configuration.md — full config schema, layering, providers, web backends
- docs/tools.md — MCP naming and deferral, web tools, computer-use backends
- docs/sandbox.md — OS confinement, per platform
- docs/plugins.md — skills, hooks, and plugin bundles
- docs/runtime.md — the optional
mermaidd service, logging, diagnostics
- docs/development.md — pre-PR gate, CI matrix, snapshot suites
- AGENTS.md — contributor and agent guardrails
Development
just check # cargo fmt --check + clippy -D warnings + guards + cargo nextest run
That is the exact pre-PR gate, and what CI's blocking jobs run.
License
MIT OR Apache-2.0
Built with Ratatui and Ollama. Inspired by Aider and Claude Code.