Skip to content
suanovaPublic
forked from genai-io/san

About

Fast, open agent harness for the terminal. One ~12 MB Go binary — bring any model and extensions into a single inspectable loop that learns as you work.

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

1 watching

Forks

 
 

Latest commit

 

History

1,105 Commits

Folders and files

Repository files navigation

< CUBE ✦ />

Minimal overhead. Maximum agent.

Small context, native speed, open all the way down.

Release Website Getting Started Docs License

English · 简体中文

Cube — animated intro

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.

Why Cube

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.

Open architecture

Overview diagram
Cube — pluggable models, search backends, personas, skills & extensions, and a self-evolving agent

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.

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 (cube inspector).
  • Plus event-driven subagent coordination, TUI themes, and prompt prediction.

Installation

Homebrew (macOS / Linux)

brew tap suanova/cube
brew install cube

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/suanova/cube/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/suanova/cube/main/install.ps1 | iex

Start 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))) uninstall

Go Install (requires Go 1.25.8+)

go install github.com/genai-io/san/cmd/cube@latest

Build 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/

Usage

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

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)

Benchmark: Cube vs Claude Code

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

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 official account 极客外传 QR code
关注公众号「极客外传」· 回复 san 或 三 入群
Cube Slack QR code
Scan or join our Slack

Fork lineage

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 to cube / CUBE.
  • Backward compatibility — Cube reads san configuration transparently: ~/.san/ is used when ~/.cube/ is absent, SAN_* env vars are read alongside CUBE_*, and SAN.md / SAN.local.md are loaded as fallbacks behind CUBE.md / CUBE.local.md. Claude Code compatibility (CLAUDE_* env vars, .claude/CLAUDE.md) is unchanged.
  • Upstream — the upstream git remote points at genai-io/san for fetching future updates:
    git remote add upstream https://github.com/genai-io/san.git
  • Migration (optional) — to move an existing san setup to the canonical cube locations:
    mv ~/.san ~/.cube

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

Apache License 2.0 - see LICENSE for details.

About

Fast, open agent harness for the terminal. One ~12 MB Go binary — bring any model and extensions into a single inspectable loop that learns as you work.

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages