genai-io/san

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

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.

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.

docs/guides/getting-started.md

Configuration

Benchmark: San vs Claude Code

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

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