Minimal overhead. Maximum agent.
Small context, native speed, open all the way down.
English · 简体中文
Open the full-quality intro ↗⚡ ~0.01s cold start · 📦 ~12 MB single binary · 🪶 zero runtime deps
Cube is a fork of san, continuing its development as a community project. Configuration from
san(~/.san,SAN_*env vars,SAN.md) is read automatically — see Fork lineage below.
Cube 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.
Three properties, and Cube 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 cube inspector.
Minimal overhead, not a minimal agent.
Cube continues san, whose name is 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 is cube.
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.
- Runs anywhere — one static binary for Windows, macOS, and Linux; the same file runs on a laptop, an edge device, or a
scratchcontainer (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 (
cube inspector). - Plus event-driven subagent coordination, TUI themes, and prompt prediction.
Homebrew (macOS / Linux)
brew tap suanova/cube
brew install cubemacOS / Linux
curl -fsSL https://raw.githubusercontent.com/suanova/cube/main/install.sh | bashWindows (PowerShell)
irm https://raw.githubusercontent.com/suanova/cube/main/install.ps1 | iexStart with cube. On first launch, choose a model and add its API key when prompted. To update later, run cube update — or brew upgrade cube if you installed via Homebrew.
Other methods
Uninstall
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/suanova/cube/main/install.sh | bash -s uninstall# Windows (PowerShell)
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/suanova/cube/main/install.ps1))) uninstallGo Install (requires Go 1.25.8+)
go install github.com/genai-io/san/cmd/cube@latestBuild from Source
git clone https://github.com/suanova/cube.git
cd cube
go build -o cube ./cmd/cube
mkdir -p ~/.local/bin && mv cube ~/.local/bin/cube # interactive
cube "explain this function" # one-shot
cube -p "do something" # print mode (no TUI), pipe-friendly
cube --continue # resume the latest session
cube --resume # pick a past session to resume
# Subcommands (run `cube <command> --help` for the full list)
cube inspector # session transcript viewer
cube agent run --prompt "..." # run a headless agent
cube plugin <list|install|enable|...> # manage plugins
cube mcp <add|list|remove|...> # manage MCP servers| What | How |
|---|---|
| Pick / switch model | /models — saved to ~/.cube/providers.json |
| Cycle thinking budget | Ctrl+T or /think (levels vary by provider) |
| Toggle permission mode | Shift+Tab (ask · auto-accept · autopilot) |
| Search / persona / memory | /search · /persona · /memory |
| Skills / agents / tools | /skills · /agents · /tools |
| Plugins / MCP / config | /plugin · /mcp · /config |
| Session / loop / misc | /fork · /compact · /loop · /init · /clear |
| All slash commands | /help |
| Send · newline · stop | Enter · Alt+Enter · Esc |
| Expand tool · cancel · exit | Ctrl+O · Ctrl+C · Ctrl+D |
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 is loaded from ~/.cube/ and <project>/.cube/ (project settings override user settings). For backward compatibility, ~/.san/ and <project>/.san/ are also read when the .cube directory is absent. Project instructions are read from .cube/CUBE.md, CUBE.md, .cube/SAN.md, SAN.md, .claude/CLAUDE.md, or CLAUDE.md, in that order.
Credentials
| Service | Variable |
|---|---|
| Anthropic (Claude) | ANTHROPIC_API_KEY or Vertex AI |
| OpenAI (GPT, o-series, Codex) | OPENAI_API_KEY, or a ChatGPT subscription (sign in via /models) |
| GitHub Copilot (all Copilot models) | a Copilot subscription (sign in via /models) |
| Google (Gemini) | GOOGLE_API_KEY |
| DeepSeek (DeepSeek V4) | DEEPSEEK_API_KEY |
| Moonshot (Kimi) | MOONSHOT_API_KEY |
| Alibaba (Qwen) | DASHSCOPE_API_KEY |
| MiniMax | MINIMAX_API_KEY |
| Z.ai (GLM / GLM Coding Plan) | BIGMODEL_API_KEY |
| SenseNova | SENSENOVA_API_KEY |
| Mimo | MIMO_API_KEY |
| Volcengine (Ark) | VOLCENGINE_API_KEY |
| Ollama (local) | OLLAMA_BASE_URL (default http://localhost:11434/v1) |
| Agnes-AI | AGNESAI_API_KEY |
| Exa search | none (default) |
| Tavily search | TAVILY_API_KEY |
| Brave search | BRAVE_API_KEY |
| Serper search | SERPER_API_KEY |
Directory layout
User-level (~/.cube/):
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/ # Agent definitions
commands/ # Custom slash commands
plugins/ # Installed plugins
projects/ # Session transcripts + indexes
Project-level (.cube/):
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)
Compared with Claude Code v2.1.112 on Apple Silicon, same model (claude-sonnet-4-6):
| Metric | Cube | 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 |
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 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
- Claude Code — Anthropic's AI coding assistant
- Aider — AI pair programming in terminal
- Continue — Open-source AI code assistant
Two ways in — WeChat for the Chinese community, Slack for everyone else:
![]() 关注公众号「极客外传」· 回复 san 或 三 入群
|
![]() Scan or join our Slack |
Cube is a fork of san and continues its development as a community project under a new name.
- Module path — the Go module path remains
github.com/genai-io/san, so existing imports keep resolving. Only the user-facing identity (binary name, config directory, env vars, branding) changed tocube/CUBE. - Backward compatibility — Cube reads
sanconfiguration transparently:~/.san/is used when~/.cube/is absent,SAN_*env vars are read alongsideCUBE_*, andSAN.md/SAN.local.mdare loaded as fallbacks behindCUBE.md/CUBE.local.md. Claude Code compatibility (CLAUDE_*env vars,.claude/CLAUDE.md) is unchanged. - Upstream — the
upstreamgit remote points atgenai-io/sanfor fetching future updates:git remote add upstream https://github.com/genai-io/san.git
- Migration (optional) — to move an existing
sansetup to the canonicalcubelocations:mv ~/.san ~/.cube
Contributions welcome! See CONTRIBUTING.md for guidelines.
Apache License 2.0 - see LICENSE for details.



