San

San is an open-source terminal agent harness: one native Go binary for model-driven work, with no Node.js or Python runtime.

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 — configure permissions, autopilot, memory, and skills for your workflow.

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

• 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, skills, plugins, MCP servers, hooks, and permission-gated subagents. /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 · benchmark).
• Permissions — three modes (ask · auto-accept · autopilot) toggled with Shift+Tab; subagents inherit the gates (details).
• 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

Start with san. On first launch, choose a model and add its API key when prompted. To update later, run san update.

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 (requires Go 1.25.8+)

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 <command> --help` for the full list)
san inspector                    # session transcript viewer
san agent run --type general-purpose --prompt "..."  # run a headless agent
san plugin <list|install|enable|...>          # manage plugins
san mcp <add|list|remove|...>                 # manage MCP servers

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.

Configuration

Configuration is loaded from ~/.san/ and <project>/.san/ (project settings override 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/           # 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):

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

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

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

Apache License 2.0 - see LICENSE for details.