Minimal harness. Maximum agent.
Small context, native speed, open all the way down.
English · 简体中文
⚡ ~0.01s cold start · 📦 ~12 MB single binary · 🪶 zero runtime deps
San is an open-source terminal agent runtime: one native Go binary, no Node.js or Python. Everything the model touches — prompt, tools, providers, extensions — stays yours to change.
Three properties, and San refuses to trade any one of them for the others.
Small — ~2.3k tokens of harness reach the model before your first message; the rest of the context window goes to your work. On disk, one 12 MB binary with zero runtime deps — it drops onto a laptop, a CI runner, or a scratch container.
Fast — ~0.01s cold start, and a full tool-use task returns in ~3.3s end to end. What you wait on is the model, not the client (benchmark).
Open — plug in models, skills, subagents, and MCP servers; write your own system prompt, autopilot goals, and self-learning strategy; replay any run in san inspector.
A minimal harness, not a minimal agent.
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.
Overview diagram
Plug in — nothing is hardwired. Models from Anthropic, OpenAI, Google, DeepSeek, Ollama, and a dozen more; the web search backend of your choice; extensions of every kind — skills, subagents, MCP servers, plugins, hooks.
Write — how the agent behaves is text you own, not something baked into the binary. Compose the system prompt (how), bundle it into a persona you can switch, give autopilot a goal, set the strategy self-learning follows.
Oversee — nothing runs unwatched. You choose how much San may do without asking, and subagents inherit that choice (permissions); the inspector replays any run exactly as the model saw it.
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/genai-io/san/main/install.sh | bashWindows (PowerShell)
irm https://raw.githubusercontent.com/genai-io/san/main/install.ps1 | iexStart with san. On first launch, choose a model and add its API key when prompted. To update later, run san update.
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))) uninstallGo Install (requires Go 1.25.8+)
go install github.com/genai-io/san/cmd/san@latestBuild 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/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 resumeSubcommands: inspector · agent · plugin · mcp — run san <command> --help for each.
| What | How |
|---|---|
| Model · thinking budget | /models · Ctrl+T |
| Permission mode | Shift+Tab (ask · auto-accept · autopilot) |
| Long-running work · learning | /autopilot · /goal · /evolve |
| All slash commands | /help |
| Keys | Enter send · Alt+Enter newline · Esc stop · Ctrl+O expand tool · Ctrl+C cancel · Ctrl+D exit |
docs/guides/getting-started.md
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 /models) |
| 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 |
Config files & layout
Settings load from ~/.san/ and <project>/.san/, with project settings overriding user settings. Project instructions are read from .san/SAN.md, SAN.md, .claude/CLAUDE.md, or CLAUDE.md, in that order.
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/ # 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)
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 |
| Harness context* | ~2.3k tokens | ~20.9k tokens | ~9x leaner |
*Context overhead is system prompt + tool schemas on an empty first turn, measured separately on San v1.22.0 vs Claude Code v2.1.220 — see method. All other rows are from the v1.13.2 / v2.1.112 run.
Comparable feature sets — the gap is client-side overhead, not capability. docs/operations/benchmark.md
- Documentation Index — map of architecture, features, operations, and references
- Architecture — architecture entrypoint and reading order
- Package Map — package ownership and dependency boundaries
- Personas — bundled system prompt, skills, agents, and settings
- System Prompt — Slot model, persona, skill/agent injection
- Subagents · Skills · Plugins · MCP
- Hooks · Permissions · Tasks
- Inspector — local web UI for transcript replay and debugging
- Per-package design under
docs/packages/— start at Package Index
- Claude Code — Anthropic's AI coding assistant
- Aider — AI pair programming in terminal
- Continue — Open-source AI code assistant
Two ways in — WeChat for the Chinese community, Slack for everyone else:
 关注公众号「极客外传」· 回复 san 或 三 入群
|
 Scan or join our Slack |
Contributions welcome! See CONTRIBUTING.md for guidelines.
Apache License 2.0 - see LICENSE for details.