bundlebox

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 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](docs/agents.md). bb uptake then reports which of the installed surfaces the sessions reached for.

Advisory lost; enforcement is the fix

bb uptake measured the gap. Over 15 sessions on this workspace the MCP tools fired in 0, pinpoint in 3 of the 13 sessions that opened five or more distinct files, and the reference tables in 5 of the 15 that ran a search. Those 13 sessions opened between 30 and 598 files each. Everything wired in front of the agent was a recommendation, and a recommendation loses to the model's own habit about three times in four.

So the wiring changed kind.

Run it, do not recommend it. UserPromptSubmit builds the brief itself on a task-shaped prompt — 0.47s against a 15s budget, because every input pinpoint reads is a stored artefact and it computes none of them. What enters the window is the map, about 300 tokens.

Serve what it found. PreToolUse denies a read whose region the brief already quotes and hands the quote back in the denial reason; denies an exact duplicate read; denies a declaration search the symbol tables already answer and hands back the rows; and asks before opening a file that was cut for budget. A file in scope is never fully blocked — Claude Code needs one successful read before it will edit, so the denial names the range and that read is allowed. Grep is the declared tool and Bash is where the measured transcripts search, so both are guarded.

Rank on specificity and path. Enforcing a brief raises the cost of a bad locate. Inverse document frequency over the candidate set stops an exact match on a name the tree uses everywhere from outscoring a loose match on a rare one, and a directory named wire now counts as evidence about what a file is for. An explicitly named file is pinned first rather than scored.

The verbs

| run | lanes on t