bundlebox

The zero-token software factory for AI coding agents.
Scan, pack, route and run work across Claude Code, Codex, Gemini CLI, Cursor, Copilot, OpenCode, Aider and any custom agent, and measure every token a session used and was spared.

An AI coding agent is billed for what it reads, and most of what it reads is orientation, not judgement: where a symbol lives, whether two tables agree, which command proves a change, what changed since last week. bundlebox answers every question a parse, a count, a path check or a set difference can answer before the agent opens, packs the answers into a brief sized to the agent's window, opens the agent under a measured-minimal flag stack, and measures afterwards what the session used and what it was spared. It never calls a model itself.

bb genesis   ->  a world     a doc becomes surfaces, rules and capabilities  0 tokens
bb scan      ->  findings    what is wrong, with evidence                    0 tokens
bb fix       ->  patches     local actuators close what they can             0 tokens
bb cookbook  ->  a board     what the RUNNING system does, run by the kernel 0 tokens
bb simulate  ->  limits      what it does at a hundred callers               0 tokens
bb compile   ->  units       what to do about the rest, packed to one window
bb pinpoint  ->  a brief     where the work is, quoted and budgeted, before a model opens
bb arc       ->  an index    every declaration in one file, read in microseconds  0 tokens
bb route     ->  lanes       who does it, where, in what wave
bb run       ->  sessions    the only verb that spends
bb finish    ->  a ledger    what proves this done, declared first and run after   0 tokens
bb git       ->  PRs         commit, push, draft PR, review, gated merge     0 tokens
bb runbook   ->  the system  is it up, is it ANSWERING, what broke since    0 tokens
bb recom     ->  an answer   what was already driven, and whether it holds   0 tokens
bb recom gate->  a decision  and therefore whether to drive at all           0 tokens
bb dotty     ->  a screen    what it showed, as rows a session can diff      0 tokens
bb sieve     ->  a window    a tool result shrunk before it is billed twice    0 tokens
bb uptake    ->  a verdict   of everything wired in, what sessions reached for 0 tokens
bb monitor   ->  the window  what the 5-hour block has left, and the guard   0 tokens
bb session   ->  the bill    what a session used and saved, measured         0 tokens
bb lathe     ->  automation  what this box did by hand more than twice, as scripts 0 tokens
bb env       ->  a checklist what a complete .bundlebox holds, and whether this has 0 tokens

Measured on the reference workspace (regenerate with bb session, bb tokens profile --probe, bb buckmaster episodes):

Install

npm i -g bundlebox
# or
curl -fsSL https://raw.githubusercontent.com/blackswanalpha/bundlebox/main/scripts/install.sh | sh

Needs Node ≥ 20 and git. Linux, macOS and Windows are supported: CI runs the full suite on all three against Node 20, 22 and 24. Two known gaps remain on Windows — a piped acceptance gate reports the last command's exit code rather than the first failure, because cmd.exe has no set -o pipefail (unpiped gates are exact), and bb session may not find transcripts, because the name Claude Code gives its projects directory there has not been verified. Three optional Rust and Python components make it faster and smarter, and everything degrades cleanly without them:

• Rust kernel (bbk): tree walks, fingerprints, token estimates, duplicate windows, symbol indexes, acceptance gates with real timeouts, worktrees. bb kernel install fetches a release binary; bb kernel build compiles it with cargo. Without it the JS implementations run, and a selftest pins both to identical answers.
• Rust index compiler (arc): compiles the derived symbol tables into one binary index the read and search guards answer from, 13x faster than scanning the tables in a cold hook process. bb arc build, recompiled by bb snapgen build when the tables move. Every reader falls back to scanning the tables when the index is absent, truncated or not an index, because "there is no index" and "nothing is declared" are different answers.
• Python expert system (bundlebox_expert, stdlib only): the rule engine with explainable derivations, confidence shrinkage, transcript signals, the process model and memory. bb buckmaster needs python3 ≥ 3.9; nothing in the zero-token path does.

There are no npm dependencies. A cron worker at 03:00 runs what is on disk or it does not run.

Start here

cd your-repo
bb init            # detect languages, agents and gates; write .bundlebox/config.json
bb doctor          # what this box can run, which runtime serves each op
bb wire --apply    # hooks, skills, instruction blocks and MCP entries for every agent
bb env up --apply  # build everything a session reads, so nothing is derived by searching
bb scan            # the detectors. Seconds, 0 tokens
bb findings        # what the store holds; bb explain <id> for one
bb pinpoint gaps   # every open finding as a located, quoted, budgeted brief
bb pinpoint next   # make one of them the ACTIVE brief the guards answer from
bb compile         # findings -> units, each packed to one window (dry run)
bb route           # units -> lanes (dry run)
bb run             # writes the exact prompt and command per lane, spawns nothing
bb run --apply     # spawns the sessions
bb finish check    # run the acceptance ledger; unproven never reads as green
bb session         # what the last session used and saved

From a document instead of from the code:

bb genesis docs/PRD.md --base http://127.0.0.1:4400   # surfaces, rules, capabilities, a seeded corpus
bb genesis plan                                       # what nothing covers, ranked and tiered
bb genesis pack                                       # one small brief per surface
bb genesis send calendar --run --spend                # the only step that costs anything
bb cookbook check && bb cookbook run                  # the kernel executes what came back
bb mainboard gaps                                     # the first stage that does not hold, and its fix
bb console                                            # one page: the pipeline, the window, every session

Every verb is a dry run until --apply. Only run and bridge send can spend.

Wiring into agents

bb wire --apply installs four things per agent detected on the box: an instruction block between markers, hooks where the agent supports them, skills where it loads them, and an MCP server entry. bb unwire removes only its own blocks, entries, hook rows and skills.

Two skills ship and cost nothing until they trigger, which is the property an instruction block does not have: it arrives in every system prompt and is billed whether the session was about it or not. bb-finish is completion discipline backed by runnable gates; antislop is the prose ruleset with what each rule costs and what to write instead.

bb mcp serves bb_pinpoint, bb_context, bb_snapgen, bb_findings, bb_scan, bb_oversight_brief, bb_explain, bb_tokens_estimate and bb_session over stdio as JSON-RPC 2.0, with no dependency.

bb wire --apply writes the entry for every agent in the table above. For an agent it does not manage:

{ "mcpServers": { "bundlebox": { "command": "npx", "args": ["-y", "bundlebox", "mcp"] } } }

Claude Code takes it as one line, or as a plugin, which carries the two skills and the hooks with it:

claude mcp add bundlebox -- npx -y bundlebox mcp
# or
/plugin marketplace add blackswanalpha/bundlebox
/plugin install bundlebox@bundlebox

Full guide, including the agents not in this table, how to wire one bundlebox does not know about, and how to drive agents as lanes: docs/agents.md. bb uptake then reports which of the installed surfaces the sessions reached for.

Advisory lost; enforcement is the fix