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, and a clean TUI.

Features

• Native tool calling — read, write, edit, delete, run commands, search the web, spawn subagents, call MCP tools
• 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 — read_only/ask/auto/full_access, cycled live with Shift+Tab; auto is classifier-backed, and gated actions prompt inline rather than erroring out
• Checkpoints — shadow-git snapshots before mutations; inspect with /checkpoints, roll back with /restore <id>
• Durable memory — the agent remembers facts across sessions; a compact index auto-loads into every prompt
• Project instructions and skills — auto-loads AGENTS.md (or CLAUDE.md) and MERMAID.md, plus task-specific playbooks loaded on demand
• MCP servers — stdio JSON-RPC client with a built-in registry of 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 — 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/<model> 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, /init to have the agent write an AGENTS.md, /usage for tokens and estimated cost, /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 --model anthropic/<model>          # Pick a model (see Remote providers below)
mermaid run "fix the tests"                # Non-interactive mode
mermaid add <name>                         # Add an MCP server from the built-in registry (e.g., context7, git)

Every flag, keyboard shortcut, and slash command: docs/cli-reference.md. mermaid --help and /help list them too.

Remote MCP servers that sign in with OAuth (Linear, Notion, Sentry, Atlassian and others) work too: mermaid add linear --url https://mcp.linear.app/mcp opens the browser to sign in, and mermaid mcp login <name> signs in again later. Tokens go to the OS keyring and refresh on their own. See docs/tools.md.

Tools

The model calls these autonomously:

MCP servers contribute tools under the mcp__<server>__<tool> 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. Servers that offer prompts add them to the / palette as /mcp__<server>__<prompt>; see docs/tools.md.

Safety

Approval policy and OS confinement are independent. The policy (read_only, ask, auto, full_access) decides what needs your say-so; the sandbox (--no-network, --confine-fs, or both with --sandbox) decides what the kernel permits regardless, and fails closed. 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.

Coming from Claude Code? A CLAUDE.md loads when there is no AGENTS.md, and the skills, commands and agents in .claude/ and .agents/ (project and ~/) load too. Put your own prompt commands in .mermaid/commands/ as markdown. See docs/plugins.md.

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 = "auto"           # 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.<name>].api_key_env. Model names are whatever the vendor currently ships; Mermaid passes them through.

Or store a key in the OS keyring with mermaid login <provider>; environment variables still win. Details: API keys and provider notes.

Architecture

Mermaid's runtime is an Elm/MVU pattern: one pure reducer (fn update(State, Msg) -> (State, Vec<Cmd>)), 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, inline approvals
• 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

License

MIT OR Apache-2.0

Built with Ratatui and Ollama. Inspired by Aider and Claude Code.