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.

Why San

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.

_{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.}

Open architecture

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.

Coordinate — more than one agent at a time. Subagents run in parallel, each on the model that suits it; workflows arrange them as a graph (how); and sessions on one machine join a group to message each other back and forth — anything that can wait holds for you (session groups).

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.

Installation

Homebrew (macOS / Linux)

brew tap genai-io/san
brew install san

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

On Windows, San runs commands under PowerShell (pwsh if present, else the built-in Windows PowerShell); set SAN_SHELL=bash, powershell, or a path to choose. With both installed, the other one is available too — turn it on in /tools.

Start with san. On first launch, choose a model and add its API key when prompted. San keeps itself current: a new release is installed in the background and the status line asks for a restart. Run san update to update right away, or brew upgrade san if you installed via Homebrew; turn background updates off in /settings › General (or set SAN_DISABLE_AUTOUPDATE=1). Model lineups, context windows and prices come from models.dev, refreshed daily (SAN_DISABLE_MODEL_REFRESH=1 to skip); correct any of them in ~/.san/models.json.

# 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 github.com/genai-io/san/cmd/san@latest

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: inspector · agent · plugin · mcp — run san --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 | | Message your other sessions | /group join · /group members · /group hold on\|off | | 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

Configuration

providers.json    # Provider connections and current model
models.json       # Your corrections to model windows, prices and reasoning efforts
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

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 | | 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

• 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
• Workflows · Session groups — subagents as a graph; sessions that message each other
• Inspector — local web UI for transcript replay and debugging
• Per-package design under docs/packages/ — start at Package Index

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:

• WeChat — 关注公众号「极客外传」· 回复 san 或 三 入群
• Slack — Join our Slack

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

Apache License 2.0 - see LICENSE for details.