San

< SAN ✦ /> A fast, open agent harness for the terminal

English · 简体中文

Open the full-quality intro ↗

⚡ ~0.01s cold start  ·  📦 ~12 MB single binary  ·  🪶 zero runtime deps

San is an open-source agent harness for the terminal — one native Go binary that wraps any model in a fast, inspectable, permission-gated loop. Bring your own model and extensions; there's no Node.js or Python runtime to install.

Why San

• Fast — a ~12 MB single binary, ~0.01s cold start, no separate runtime.
• Open — swap the model, search, and tools at runtime; bring your own persona profiles and extensions.
• Harness — tune policies, not just parts: customize auto-review to cut human-in-the-loop, and self-learning — memory and skills it grows and refines — as you work.

The name — San, written 三 ("three") and drawn ☰. From the Dao De Jing, 三生万物 — "three begets the ten-thousand things": one runtime that becomes any agent, running a three-step loop (reason → act → observe). The command stays san.

Features

Open architecture  ·  overview diagram

• Models — Anthropic, OpenAI, Google, DeepSeek, Moonshot, Alibaba, MiniMax, Z.ai (GLM), SenseNova, Mimo, Volcengine (Ark), Ollama (local), Agnes-AI. /model
• Search — Exa, Tavily, Brave, Serper. /search
• Personas & extensions — reusable profiles, plus Claude Code skills, plugins, MCP servers, hooks, and sandboxed subagents — all run unmodified. /persona
• Self-learning — opt-in; distills durable memory and reusable skills with configurable cadence and caps. (Level 1; deeper levels on the way.)

Engineering

• Runs anywhere — one static binary for Windows, macOS, and Linux; the same file runs on a laptop, an edge device, or a scratch container ([footprint](docs/operations/footprint.md) · [benchmark](#benchmark-san-vs-claude-code)).
• Permissions — three modes (ask · auto-accept · auto-review) toggled with Shift+Tab; subagents inherit the gates ([details](docs/concepts/permission-model.md)).
• Sessions — auto-save, resume (--continue / --resume), fork (/fork), auto-compaction (/compact), and per-message cost tracking.
• Inspector — replay transcripts and inspect system prompts in a local web UI (san inspector).
• Plus event-driven subagent coordination, TUI themes, and prompt prediction.

Installation

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/genai-io/san/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/genai-io/san/main/install.ps1 | iex

Re-run to upgrade.

Other methods

Uninstall

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/genai-io/san/main/install.sh | bash -s uninstall

# Windows (PowerShell)
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/genai-io/san/main/install.ps1))) uninstall

Go Install

go install github.com/genai-io/san/cmd/san@latest

Build from Source

git clone https://github.com/genai-io/san.git
cd san
go build -o san ./cmd/san
mkdir -p ~/.local/bin && mv san ~/.local/bin/

Usage

san                              # interactive
san "explain this function"      # one-shot
san -p "do something"            # print mode (no TUI), pipe-friendly
san --continue                   # resume the latest session
san --resume                     # pick a past session to resume

# Subcommands (run `san  --help` for the full list)
san inspector                    # session transcript viewer
san agent run --type Explore --prompt "..."   # run a headless agent
san plugin           # manage plugins
san mcp                  # manage MCP servers

| What | How | |---|---| | Pick / switch model | /model — saved to ~/.san/providers.json | | Cycle thinking budget | Ctrl+T or /think (levels vary by provider) | | Toggle permission mode | Shift+Tab (ask · auto-accept · auto-review) | | Search / persona / memory | /search · /persona · /memory | | Skills / agents / tools | /skills · /agents · /tools | | Plugins / MCP / config | /plugin · /mcp · /config | | Session / loop / misc | /fork · /compact · /loop · /glob · /init · /clear | | All slash commands | /help | | Send · newline · stop | Enter · Alt+Enter · Esc | | Expand tool · cancel · exit | Ctrl+O · Ctrl+C · Ctrl+D |

For API keys, set the matching env var (see Credentials below) or paste when prompted on first launch. Full walkthrough: [docs/guides/getting-started.md](docs/guides/getting-started.md).

Configuration

Config lives in ~/.san/ (user) and /.san/ (project, overrides user). A SAN.md or CLAUDE.md at the project root is auto-loaded into the system prompt.

Credentials

| Service | Variable | |:--------|:---------| | Anthropic (Claude) | ANTHROPIC_API_KEY or Vertex AI | | OpenAI (GPT, o-series, Codex) | OPENAI_API_KEY, or a ChatGPT subscription (sign in via /model) | | Google (Gemini) | GOOGLE_API_KEY | | DeepSeek (DeepSeek V4) | DEEPSEEK_API_KEY | | Moonshot (Kimi) | MOONSHOT_API_KEY | | Alibaba (Qwen) | DASHSCOPE_API_KEY | | MiniMax | MINIMAX_API_KEY | | Z.ai (GLM / GLM Coding Plan) | BIGMODEL_API_KEY | | SenseNova | SENSENOVA_API_KEY | | Mimo | MIMO_API_KEY | | Volcengine (Ark) | VOLCENGINE_API_KEY | | Ollama (local) | OLLAMA_BASE_URL (default http://localhost:11434/v1) | | Agnes-AI | AGNESAI_API_KEY | | Exa search | none_ (default) | | Tavily search | TAVILY_API_KEY | | Brave search | BRAVE_API_KEY | | Serper search | SERPER_API_KEY |

Directory layout

User-level (~/.san/):

providers.json    # Provider connections and current model
settings.json     # Permissions, hooks, env, active persona
skills.json       # Skill states
personas/         # Persona bundles: system prompt parts, skills, settings
skills/           # Custom skill definitions
agents/           # Custom agent definitions
commands/         # Custom slash commands
plugins/          # Installed plugins
projects/         # Session transcripts + indexes

Project-level (.san/):

settings.json       # Permissions, hooks, disabled tools
mcp.json            # MCP server definitions (team shared)
mcp.local.json      # MCP server definitions (personal, git-ignored)
personas/           # Project-scoped persona bundles (override user-level)
agents/*.md         # Subagent definitions
skills/*/SKILL.md   # Skills
commands/*.md       # Slash commands
plugins/            # Project-level plugins
plugins-local/      # Local plugins (git-ignored)

Benchmark: San vs Claude Code

Compared with Claude Code v2.1.112 on Apple Silicon, same model (claude-sonnet-4-6):

| Metric | San | Claude Code | Advantage | |--------|---------|-------------|-----------| | Download size | 12 MB | 63 MB (+ Node.js 112 MB) | 5x smaller | | Disk footprint | 38 MB | 175 MB | 4.6x smaller | | Startup time | ~0.01s | ~0.20s | 20x faster | | Startup memory | ~32 MB | ~189 MB | 5.8x less | | Simple task | ~2.4s / 39 MB | ~10.4s / 286 MB | 4.3x faster, 7.3x less memory | | Tool-use task | ~3.3s / 39 MB | ~26.0s / 285 MB | 7.9x faster, 7.2x less memory |

Both tools have comparable features (hooks, skills, plugins, session, MCP, etc.). The performance gap comes from Go's native compilation, minimal architecture design, and lean prompt engineering — vs Node.js V8/JIT/GC runtime overhead.

See full details: [docs/operations/benchmark.md](docs/operations/benchmark.md)

Documentation

• [Documentation Index](docs/index.md) — map of architecture, features, operations, and references
• [Architecture](docs/concepts/architecture.md) — architecture entrypoint and reading order
• [Package Map](docs/reference/package-map.md) — package ownership and dependency boundaries
• [Personas](docs/concepts/persona.md) — bundled system prompt, skills, agents, and settings
• [System Prompt](docs/concepts/harness-channels.md) — Slot model, persona, skill/agent injection
• [Subagents](docs/packages/2-feature/subagent.md) · [Skills](docs/packages/2-feature/skill.md) · [Plugins](docs/packages/2-feature/plugin.md) · [MCP](docs/packages/2-feature/mcp.md)
• [Hooks](docs/packages/2-feature/hook.md) · [Permissions](docs/concepts/permission-model.md) · [Tasks](docs/packages/2-feature/task.md)
• [Inspector](docs/packages/2-feature/inspector.md) — local web UI for transcript replay and debugging
• Per-package design under [docs/packages/](docs/packages/) — start at [Package Index](docs/packages/index.md)

Related Projects

• Claude Code — Anthropic's AI coding assistant
• Aider — AI pair programming in terminal
• Continue — Open-source AI code assistant

Community

Two ways in — WeChat for the Chinese community, Slack for everyone else:

关注公众号「极客外传」· 回复 san 或 三 入群

Scan or join our Slack

Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

License

Apache License 2.0 - see [LICENSE](LICENSE) for details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: genai-io
• Source: genai-io/san
• License: Apache-2.0
• Homepage: https://genai-io.github.io/san/

Install and usage instructions live in the source repository linked above.