< SAN ✦ />

San is a terminal-native unified runtime for specialized agents — coding and beyond — built on five pluggable pillars: LLMs, search backends, personas, skills & extensions (skills, plugins, MCP servers, subagents), and a self-evolving agent that levels up as you work. Written in Go.

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

• LLM providers — Anthropic, OpenAI, Google, DeepSeek, Moonshot, Alibaba, MiniMax, Z.ai (GLM); swap via /model.
• Search backends — Exa, Tavily, Brave, Serper; swap via /search.
• Personas — Markdown identities scoped to user or project; swap via /identity (details).
• Skills & extensions — Claude Code skills, plugins, and MCP servers run unmodified; sandboxed subagents; lifecycle hooks (shell, LLM, agent, HTTP); auto-loaded project memory.
• Self-evolving — every few turns a background reviewer distills your recent work into durable memory and reusable skills, so the agent levels up as you work. (Level 1 available; deeper levels on the way.)

Engineering

• Runs anywhere — A single ~12 MB binary with zero runtime dependencies (no Node.js, no Python). Native Go: ~0.01s cold start, ~32 MB baseline, and the same file runs unchanged on a laptop, an edge device, or in a scratch container (footprint · benchmark).
• Event-driven coordination — Parallel subagent execution via a pub/sub hub (architecture).
• Session persistence — Auto-save, resume, fork, and automatic context compaction.
• Prompt prediction — Speculative completion of likely next prompts to reduce latency.
• Session inspector — Local web UI for transcript replay, system prompt forensics, and live-tail of active sessions (san inspector).

Installation

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

Re-run to upgrade. To uninstall:

curl -fsSL https://raw.githubusercontent.com/genai-io/san/main/install.sh | bash -s 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
cat main.go | san "review"     # piped input
san --continue                 # resume latest session
san --resume                   # pick a past session
san inspector                  # open session transcript viewer

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

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

User-level (~/.san/):

providers.json    # Provider connections and current model
settings.json     # Permissions, hooks, env, identity
skills.json       # Skill states
identities/       # Custom personas (see /identity)
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
identities/*.md    # Project-scoped personas (override user-level)
agents/*.md        # Subagent definitions
skills/*/SKILL.md  # Skills
commands/*.md      # Slash commands

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
• System Prompt — Slot model, identity, 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.