codebase

An AI coding agent that lives in your terminal.
Any LLM. Reads your project, writes code, runs commands, ships work.

Install

Requires Node.js ≥ 20.

# macOS / Linux
curl -fsSL https://codebase.design/install.sh | sh

# Windows (PowerShell)
irm https://codebase.design/install.ps1 | iex

# any platform, with npm
npm i -g codebase-cli

Then, in any project:

cd your-project
codebase

Type, hit enter. It reads files, edits code, runs tests, and shows its work. /help lists everything.

For a trusted one-shot build from scripts or CI:

codebase auto "build a small dashboard and run the tests"
codebase auto --reliable "fix the auth refresh race and prove it"

--reliable fails the run unless the agent keeps a task list, moves completed tasks through in_progress without overlapping active work, attaches evidence to each completed task, records a passing verification command after the final file change, ties file mutations and verification to completed task work, and requires the final answer to positively name the fresh verification command. For read-only or memory-only runs with no file mutations, the final answer must state that no file-change verification was needed. With --output json, the result includes a receipt: task lifecycle, per-task evidence, file mutations, verification evidence, final-answer proof, usage, and rewind checkpoints. Obvious secret-looking values are redacted before receipts are saved. Failed receipt summaries show gate status and next actions instead of only dumping raw audit strings. Inspect the latest one with codebase receipt, list saved runs with codebase receipt list, or export markdown with codebase receipt export --out receipt.md.

For launch-proof benchmark sweeps:

codebase bench run --scenario all --runs 3 --reliable true
codebase bench report <sweep-id> --out docs/benchmarks/<sweep-id>.md --json-out docs/benchmarks/<sweep-id>.json

Benchmark rows include CLI version, repo commit/dirty state, Node version, isolated-HOME status, receipt health, task evidence, verification evidence, tool calls, cost, and redacted public artifacts. The packaged command writes sweep results under ./bench/results/<sweep-id> in the directory where you run it.

Pick your LLM

Bring your own key — Anthropic, OpenAI, Groq, OpenRouter, Mistral, Ollama, or any OpenAI-compatible endpoint:

ANTHROPIC_API_KEY=sk-ant-... codebase     # or OPENAI_API_KEY, GROQ_API_KEY, …

Or sign in once and skip the key wrangling — codebase.design gives you a free taste of open-weight models, and a paid account uncaps those plus the frontier models (Claude Opus/Sonnet, GPT-5, …) behind one bill. First run walks you through it; it even auto-detects a local LLM (LM Studio / Ollama / vLLM).

codebase auth login
codebase project build --wait "build a launch waitlist page"

OAuth uses Codebase Auto by default (codebase/d4f, in-house DeepSeek V4 Flash). Swap models live with /model. Set reasoning depth with /effort. project build hands a prompt to the web builder and prints the session, status, event stream, and preview URL when you pass --wait.

Signed-in sessions also get hosted web search with no extra key. BYOK users can set TAVILY_API_KEY, BRAVE_API_KEY, or SEARXNG_URL; local search providers take priority over the hosted service. Run codebase doctor to verify which path is active.

Use Codebase from an ACP client

Codebase speaks the Agent Client Protocol over stdio:

codebase acp

Buzz

Buzz accepts Codebase as a custom ACP harness. Current Buzz builds only attach their channel-publishing MCP to recognized runtime names, so use this small compatibility launcher until Buzz supports MCP injection for every custom harness:

mkdir -p ~/.local/share/codebase-buzz
cat > ~/.local/share/codebase-buzz/codex-acp <<'SH'
#!/bin/sh
if [ "$#" -eq 1 ] && [ "$1" = "--version" ]; then
  echo "codebase-acp 1.1.7"
  exit 0
fi
[ "$#" -gt 0 ] || set -- acp
exec codebase "$@"
SH
chmod +x ~/.local/share/codebase-buzz/codex-acp

Then add the Buzz custom harness:

Name: Codebase
Command: /Users/YOU/.local/share/codebase-buzz/codex-acp
Arguments: (leave empty)

The launcher still runs Codebase; the codex-acp filename lets current Buzz versions supply the MCP tools an agent needs to publish its answer into the channel. Without that bridge, Buzz may show Codebase's generated text in agent activity but never post it as a message.

Buzz can discover the models available to your Codebase account. Each ACP session gets its own working directory and conversation, accepts client-supplied MCP servers, streams assistant and tool progress, supports cancellation, and routes write/shell approvals through the client's permission UI.

What makes it good

• 🏁 Tournaments. /tournament <task> races several agents on the same change in isolated worktrees, a judge ranks them, you merge the winner. --models opus,sonnet,haiku pits models head-to-head on your code.
• Receipts. codebase auto --reliable turns a one-shot task into an audited run: task lifecycle, per-task evidence, verification, tool calls, usage, and checkpoints are saved locally and inspectable with codebase receipt.
• ↺ Rewind anything. /rewind rolls the conversation and the files back to before any earlier prompt — a bad turn fully un-happens. Every edit is checkpointed.
• 🧠 Remembers across sessions. Pulls durable facts (your prefs, project decisions, the rules you set) out of a session, then recalls matching notes with file/source/session/last-used/staleness labels. #note to add one by hand; /memory list|show|forget to inspect or clean them up.
• 🔌 MCP. Connect external tool servers (filesystem, Postgres, git, fetch, …) over stdio or remote HTTP, OAuth and all. Their tools splice straight into the agent.
• ACP. Run codebase acp to use Codebase from Buzz and other ACP clients, with model discovery, streamed tool activity, cancellation, permissions, and client-supplied MCP servers.
• 🤖 Subagents. Fan out read-only researchers or write-capable workers that keep their tool-noise out of your main context — each can run in its own git worktree, on its own model and reasoning level.
• 🪝 Hooks. Shell commands on lifecycle events (pre/post tool, edit, prompt, session start/end) — run a formatter on save, block secrets, commit on exit.
• 🌐 SSH. Run commands on enrolled remote hosts by name, behind the same safety validator as the local shell.

…plus a fast differential TUI (clean copy-mode with Ctrl-O, image paste with Ctrl-V, history search with Ctrl-R, $EDITOR compose with Ctrl-G), plan mode for a cheap Q&A pass before editing, auto-compaction of long sessions, multi-session resume (/resume, /rename, /tag), TS/JS code navigation for definitions/type definitions/implementations/references/hover/symbols/diagnostics, skills & output styles as drop-in markdown, 45+ tools behind one interface, and effect-based permissions you can teach with /permissions or preview with /permissions simulate "npm test && git status".

Cheat sheet

/model /effort /plan /context /memory /tournament /rewind /resume /permissions /mcp /help
!cmd     run a shell command without spending a turn
@path    pin a file into the next prompt
#note    save a memory   ·   \<Enter>  multi-line   ·   Ctrl-C  stop turn / exit

Type while it's working — your prompt queues and fires when the turn ends.

Built on pi

The agent loop, provider adapters, and session protocol come from pi (MIT). Go give them a star.

More

• CLAUDE.md — full feature reference
• .settings/ — tenets, architecture, extending, testing
• docs/MIGRATION_v1_to_v2.md — upgrading from the Go v1 binary
• /help inside the CLI — every command and shortcut

License

MIT.