Mermaid is an open-source AI pair programming tool designed to enhance coding workflows in the terminal. It acts as an intelligent assistant for developers, leveraging multiple AI providers such as Ollama, Anthropic, Gemini, and OpenAI, among others.
Key Features:
Multi-Provider Support: Works seamlessly with various AI models, including local and cloud-based options, ensuring flexibility and adaptability.
Native Tool Calling: Enables direct interaction with system tools, allowing the AI to execute commands, manage files, and access web resources.
Computer Use Capabilities: Offers screenshot and click functionalities for enhanced interaction, particularly useful in GUI environments.
Plan Mode: Provides a structured approach for collaboration, where the AI generates plans that users can approve before implementation.
Non-Interactive Mode: Suitable for scripting and CI/CD pipelines, allowing automation without real-time interaction.
Target Audience and Benefits:
Ideal for developers and AI enthusiasts seeking to integrate intelligent assistance into their coding processes. Mermaid enhances productivity by automating repetitive tasks, improving code quality through collaborative planning, and offering a seamless integration with existing development tools. Its availability via Winget ensures easy deployment, making it accessible and convenient for users across different platforms.
Mermaid stands out as a versatile tool that empowers developers to leverage AI effectively, fostering innovation and efficiency in software development.
README
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
# 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 on Linux/macOS 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, nothing yet 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.