{"id":51030008,"url":"https://github.com/genai-io/san","last_synced_at":"2026-06-21T23:31:02.809Z","repository":{"id":258337042,"uuid":"852902752","full_name":"genai-io/san","owner":"genai-io","description":"Open-source AI agent. Lives in your terminal.","archived":false,"fork":false,"pushed_at":"2026-06-12T05:49:56.000Z","size":28732,"stargazers_count":56,"open_issues_count":16,"forks_count":26,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-06-12T07:15:17.988Z","etag":null,"topics":["ai-agents","automation","claude-code","cli","coding","gemini-cli","golang","llm","opencode","provider-agnostic","terminal","workflow"],"latest_commit_sha":null,"homepage":"https://genai-io.github.io/san/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/genai-io.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-09-05T16:16:25.000Z","updated_at":"2026-06-12T05:50:00.000Z","dependencies_parsed_at":"2026-03-15T07:02:25.258Z","dependency_job_id":"01dbe053-3d1c-46cb-8fcc-df1c3c9c093b","html_url":"https://github.com/genai-io/san","commit_stats":{"total_commits":53,"total_committers":1,"mean_commits":53.0,"dds":0.0,"last_synced_commit":"0cbfdbfa83ac5de123e6626f2a68a19b7623bc9b"},"previous_names":["yanmxa/omni-agent","yanmxa/zengent","yanmxa/zen-agent","yanmxa/genpilot","yanmxa/chat-agent","yanmxa/gencode","genai-io/gen-code","genai-io/san"],"tags_count":100,"template":false,"template_full_name":null,"purl":"pkg:github/genai-io/san","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genai-io%2Fsan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genai-io%2Fsan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genai-io%2Fsan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genai-io%2Fsan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/genai-io","download_url":"https://codeload.github.com/genai-io/san/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genai-io%2Fsan/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34629658,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","claude-code","cli","coding","gemini-cli","golang","llm","opencode","provider-agnostic","terminal","workflow"],"created_at":"2026-06-21T23:31:01.403Z","updated_at":"2026-06-21T23:31:02.792Z","avatar_url":"https://github.com/genai-io.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e\u0026lt; SAN ✦ /\u0026gt;\u003c/h1\u003e\n  \u003cp\u003e\u003cstrong\u003eAn open, ~12 MB runtime for fast AI agents\u003c/strong\u003e\u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/genai-io/san/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/genai-io/san?style=flat-square\" alt=\"Release\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://goreportcard.com/report/github.com/genai-io/san\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/genai-io/san?style=flat-square\" alt=\"Go Report Card\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://genai-io.github.io/san/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Website-0d9488?style=flat-square\" alt=\"Website\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://genai-io.github.io/san/getting-started.html\"\u003e\u003cimg src=\"https://img.shields.io/badge/Getting%20Started-0d9488?style=flat-square\" alt=\"Getting Started\"\u003e\u003c/a\u003e\n    \u003ca href=\"docs/index.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/Docs-0d9488?style=flat-square\" alt=\"Docs\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.producthunt.com/products/san?launch=san\"\u003e\u003cimg src=\"https://img.shields.io/badge/Product%20Hunt-da552f?style=flat-square\u0026logo=producthunt\u0026logoColor=white\" alt=\"Product Hunt\"\u003e\u003c/a\u003e\n    \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n  \u003cp\u003e\n    \u003cstrong\u003eEnglish\u003c/strong\u003e · \u003ca href=\"README.zh.md\"\u003e简体中文\u003c/a\u003e\n  \u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://genai-io.github.io/san/intro.html\"\u003e\u003cimg src=\"assets/san-intro.gif\" alt=\"San — animated intro\" width=\"100%\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n  \u003csub\u003e\u003ca href=\"https://genai-io.github.io/san/intro.html\"\u003eOpen the full-quality intro ↗\u003c/a\u003e\u003c/sub\u003e\n  \u003cp\u003e\n    ⚡ \u003cstrong\u003e~0.01s\u003c/strong\u003e cold start\u0026nbsp;\u0026nbsp;·\u0026nbsp;\u0026nbsp;📦 \u003cstrong\u003e~12 MB\u003c/strong\u003e single binary\u0026nbsp;\u0026nbsp;·\u0026nbsp;\u0026nbsp;🪶 \u003cstrong\u003ezero\u003c/strong\u003e runtime deps — no Node.js, no Python\n  \u003c/p\u003e\n\u003c/div\u003e\n\nSan is a terminal-native **unified runtime for specialized agents** — coding and beyond. Plug in any model and search backend, switch personas, and run your skills, plugins, MCP servers, and subagents unmodified. And it's self-evolving, learning as you work. One Go binary, runs anywhere.\n\n\u003csub\u003e*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`.*\u003c/sub\u003e\n\n## Features\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/san.png\" alt=\"San — pluggable models, search backends, personas, skills \u0026amp; extensions, and a self-evolving agent\" width=\"100%\"\u003e\n\u003c/div\u003e\n\n### Open architecture\n\n- **LLM providers** — Anthropic, OpenAI, Google, DeepSeek, Moonshot, Alibaba, MiniMax, Z.ai (GLM), SenseNova, Mimo, Volcengine (Ark), Ollama (local), Agnes-AI; swap via `/model`.\n- **Search backends** — Exa, Tavily, Brave, Serper; swap via `/search`.\n- **Personas** — Markdown identities scoped to user or project; swap via `/identity` ([details](docs/concepts/harness-channels.md#identity-custom-personas)).\n- **Skills \u0026 extensions** — Claude Code skills, plugins, and MCP servers run unmodified; sandboxed subagents; lifecycle hooks (shell, LLM, agent, HTTP); auto-loaded project memory.\n- **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.)*\n\n### Engineering\n\n- **Runs anywhere** — A single ~12 MB binary, zero runtime dependencies (no Node.js, no Python). Native Go: ~0.01s cold start, ~32 MB baseline; the same file runs unchanged on a laptop, an edge device, or a `scratch` container. Windows, macOS, and Linux builds in release artifacts ([footprint](docs/operations/footprint.md) · [benchmark](#benchmark-san-vs-claude-code)).\n- **Permission system** — Mode-based access control: ask (default) and auto-accept, toggled with `Shift+Tab`. Subagents inherit permission gates for sandboxed execution ([details](docs/concepts/permission-model.md)).\n- **Event-driven coordination** — Parallel subagents via a pub/sub hub ([architecture](docs/packages/subagent.md)).\n- **Session persistence** — Auto-save, resume (`--continue`, `--resume`), fork (`/fork`), and automatic context compaction (`/compact`).\n- **Cost tracking** — Per-message and per-session token costs across all providers.\n- **Theme \u0026 appearance** — Switch TUI color themes via the `/config` Appearance panel; \"auto\" matches your terminal.\n- **Prompt prediction** — Speculative completion of likely next prompts to cut latency.\n- **Session inspector** — Local web UI for transcript replay, system-prompt forensics, and live-tail of active sessions (`san inspector`).\n\n\n## Installation\n\n**macOS / Linux**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/genai-io/san/main/install.sh | bash\n```\n\n**Windows (PowerShell)**\n\n```powershell\nirm https://raw.githubusercontent.com/genai-io/san/main/install.ps1 | iex\n```\n\nRe-run to upgrade.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOther methods\u003c/b\u003e\u003c/summary\u003e\n\n**Uninstall**\n\n```bash\n# macOS / Linux\ncurl -fsSL https://raw.githubusercontent.com/genai-io/san/main/install.sh | bash -s uninstall\n```\n\n```powershell\n# Windows (PowerShell)\n\u0026 ([scriptblock]::Create((irm https://raw.githubusercontent.com/genai-io/san/main/install.ps1))) uninstall\n```\n\n**Go Install**\n\n```bash\ngo install github.com/genai-io/san/cmd/san@latest\n```\n\n**Build from Source**\n\n```bash\ngit clone https://github.com/genai-io/san.git\ncd san\ngo build -o san ./cmd/san\nmkdir -p ~/.local/bin \u0026\u0026 mv san ~/.local/bin/\n```\n\n\u003c/details\u003e\n\n## Usage\n\n```bash\nsan                              # interactive\nsan \"explain this function\"      # one-shot\nsan -p \"do something\"            # print mode (no TUI), pipe-friendly\nsan --continue                   # resume the latest session\nsan --resume                     # pick a past session to resume\n\n# Subcommands (run `san \u003ccommand\u003e --help` for the full list)\nsan inspector                    # session transcript viewer\nsan agent run --type Explore --prompt \"...\"   # run a headless agent\nsan plugin \u003clist|install|enable|...\u003e          # manage plugins\nsan mcp \u003cadd|list|remove|...\u003e                 # manage MCP servers\n```\n\n| What | How |\n|---|---|\n| Pick / switch model | `/model` — saved to `~/.san/providers.json` |\n| Cycle thinking budget | `Ctrl+T` or `/think` (levels vary by provider) |\n| Toggle permission mode | `Shift+Tab` (ask · auto-accept) |\n| Search / identity / memory | `/search` · `/identity` · `/memory` |\n| Skills / agents / tools | `/skills` · `/agents` · `/tools` |\n| Plugins / MCP / config | `/plugin` · `/mcp` · `/config` |\n| Session / loop / misc | `/fork` · `/compact` · `/loop` · `/glob` · `/init` · `/clear` |\n| All slash commands | `/help` |\n| Send · newline · stop | `Enter` · `Alt+Enter` · `Esc` |\n| Expand tool · cancel · exit | `Ctrl+O` · `Ctrl+C` · `Ctrl+D` |\n\nFor API keys, set the matching env var (see Credentials below) or paste when prompted on first launch. Full walkthrough: [`docs/guides/getting-started.md`](docs/guides/getting-started.md).\n\n### Configuration\n\nConfig lives in `~/.san/` (user) and `\u003cproject\u003e/.san/` (project, overrides user). A `SAN.md` or `CLAUDE.md` at the project root is auto-loaded into the system prompt.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCredentials\u003c/b\u003e\u003c/summary\u003e\n\n| Service | Variable |\n|:--------|:---------|\n| **Anthropic** (Claude) | `ANTHROPIC_API_KEY` or [Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/claude) |\n| **OpenAI** (GPT, o-series, Codex) | `OPENAI_API_KEY` |\n| **Google** (Gemini) | `GOOGLE_API_KEY` |\n| **DeepSeek** (DeepSeek V4) | `DEEPSEEK_API_KEY` |\n| **Moonshot** (Kimi) | `MOONSHOT_API_KEY` |\n| **Alibaba** (Qwen) | `DASHSCOPE_API_KEY` |\n| **MiniMax** | `MINIMAX_API_KEY` |\n| **Z.ai** (GLM / GLM Coding Plan) | `BIGMODEL_API_KEY` |\n| **SenseNova** | `SENSENOVA_API_KEY` |\n| **Mimo** | `MIMO_API_KEY` |\n| **Volcengine** (Ark) | `VOLCENGINE_API_KEY` |\n| **Ollama** (local) | `OLLAMA_BASE_URL` (default `http://localhost:11434/v1`) |\n| **Agnes-AI** | `AGNESAI_API_KEY` |\n| **Exa** search | _none_ (default) |\n| **Tavily** search | `TAVILY_API_KEY` |\n| **Brave** search | `BRAVE_API_KEY` |\n| **Serper** search | `SERPER_API_KEY` |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDirectory layout\u003c/b\u003e\u003c/summary\u003e\n\nUser-level (`~/.san/`):\n\n```\nproviders.json    # Provider connections and current model\nsettings.json     # Permissions, hooks, env, identity\nskills.json       # Skill states\nidentities/       # Custom personas (see /identity)\nskills/           # Custom skill definitions\nagents/           # Custom agent definitions\ncommands/         # Custom slash commands\nplugins/          # Installed plugins\nprojects/         # Session transcripts + indexes\n```\n\nProject-level (`.san/`):\n\n```\nsettings.json       # Permissions, hooks, disabled tools\nmcp.json            # MCP server definitions (team shared)\nmcp.local.json      # MCP server definitions (personal, git-ignored)\nidentities/*.md     # Project-scoped personas (override user-level)\nagents/*.md         # Subagent definitions\nskills/*/SKILL.md   # Skills\ncommands/*.md       # Slash commands\nplugins/            # Project-level plugins\nplugins-local/      # Local plugins (git-ignored)\n```\n\n\u003c/details\u003e\n\n## Benchmark: San vs Claude Code\n\nCompared with [Claude Code](https://claude.ai/code) v2.1.112 on Apple Silicon, same model (`claude-sonnet-4-6`):\n\n| Metric | San | Claude Code | Advantage |\n|--------|---------|-------------|-----------|\n| Download size | 12 MB | 63 MB (+ Node.js 112 MB) | **5x smaller** |\n| Disk footprint | 38 MB | 175 MB | **4.6x smaller** |\n| Startup time | ~0.01s | ~0.20s | **20x faster** |\n| Startup memory | ~32 MB | ~189 MB | **5.8x less** |\n| Simple task | ~2.4s / 39 MB | ~10.4s / 286 MB | **4.3x faster, 7.3x less memory** |\n| Tool-use task | ~3.3s / 39 MB | ~26.0s / 285 MB | **7.9x faster, 7.2x less memory** |\n\nBoth 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.\n\nSee full details: [docs/operations/benchmark.md](docs/operations/benchmark.md)\n\n## Documentation\n\n- [Documentation Index](docs/index.md) — map of architecture, features, operations, and references\n- [Architecture](docs/architecture.md) — architecture entrypoint and reading order\n- [Package Map](docs/reference/package-map.md) — package ownership and dependency boundaries\n- [System Prompt](docs/concepts/harness-channels.md) — Slot model, identity, skill/agent injection\n- [Subagents](docs/packages/subagent.md) · [Skills](docs/packages/skill.md) · [Plugins](docs/packages/plugin.md) · [MCP](docs/packages/mcp.md)\n- [Hooks](docs/packages/hook.md) · [Permissions](docs/concepts/permission-model.md) · [Tasks](docs/packages/task.md)\n- [Inspector](docs/inspector.md) — local web UI for transcript replay and debugging\n- Per-package design under [`docs/packages/`](docs/packages/) — start at [Package Index](docs/packages/index.md)\n\n## Related Projects\n\n- [Claude Code](https://claude.ai/code) — Anthropic's AI coding assistant\n- [Aider](https://github.com/paul-gauthier/aider) — AI pair programming in terminal\n- [Continue](https://github.com/continuedev/continue) — Open-source AI code assistant\n\n## Community\n\nTwo ways in — WeChat for the Chinese community, Slack for everyone else:\n\n\u003cdiv align=\"center\"\u003e\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\" width=\"50%\"\u003e\n  \u003cimg src=\"assets/wechat.jpg\" alt=\"WeChat official account 极客外传 QR code\" width=\"200\"\u003e\u003cbr\u003e\n  \u003csub\u003e关注公众号「极客外传」· 回复 \u003ccode\u003esan\u003c/code\u003e 或 \u003ccode\u003e三\u003c/code\u003e 入群\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"50%\"\u003e\n  \u003cimg src=\"assets/slack.png\" alt=\"San Slack QR code\" width=\"200\"\u003e\u003cbr\u003e\n  \u003csub\u003eScan or \u003ca href=\"https://join.slack.com/t/sanaico/shared_invite/zt-3zvfr8v6f-dchFpvpufY7fKA7tG7lhIg\"\u003ejoin our Slack\u003c/a\u003e\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\u003c/div\u003e\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nApache License 2.0 - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenai-io%2Fsan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgenai-io%2Fsan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenai-io%2Fsan/lists"}