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 installfetches a release binary;bb kernel buildcompiles 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 bybb snapgen buildwhen 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 buckmasterneeds 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
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
The budget model
projected = overhead + brief + payload × churn + reserve
Overhead is probed, not assumed. Payload is the located region plus a widening
allowance when a symbol is named, not the file. Churn is the term everyone
forgets and it measures near 2.4. Reserve is per kind of unit. The verdict is
FITS, TIGHT, SPLIT or HEAVY, and a split respects directory locality.
Five levers act on those terms, in measured order: the lean flag stack, region
not file, say it once, a cache-stable prefix, and optionally a local compression
proxy on the wire reported on its own row. See EXPLANATION.md.
Measured vs estimated
Two kinds of number appear in every report and are never added: used and
cache-saved are measured off the transcript; automation-saved is an estimate
printed as a range. A model with no price is reported with tokens and no cost.
A verb that could not look says unknown. A unit with no acceptance is
unproven, not passed.
There is a third number and it is measured on both sides. bb bench runs the
same task twice — once with the factory in front of it and once without — and
reports the difference:
bb bench init # a suite from the open findings that name a file
bb bench run # both arms, per task, with the losses printed
bb bench show --json
BARE greps the tree for the task's terms, reads the search output and opens a
range around the first hit in each of the top files, which is what a session
does on a box where nothing is installed. PACKED is the
one bb pinpoint prompt for the same task. Both arms are counted by the same
estimator over text on disk, so neither calls a model and a second run on the
same tree returns the same number. A task that costs more packed than bare is
printed in the table, not dropped.
Every bb pinpoint brief carries one more section, and it is the one worth
reading first: what this brief does not settle. No gate detected, nothing in
the symbol tables matched, no region located, no evidence on file, a scope that
had to be cut to fit — each is stated with its reason rather than filled in by
guessing, and scored so two briefs can be compared. A question costs one turn;
a wrong assumption costs the review that catches it.
The console
bb console serves one read-only page for the workspace on
127.0.0.1:7788, and bb console build writes the same page as a single
file with the state embedded. It binds to loopback, has no write route, and
nothing on it calls a model.
It pushes rather than polls. The store is files, so the filesystem already
knows when something changed: /api/stream watches it, recomputes the state
once per change however many tabs are open, and sends it. A 10s timer was wrong
in both directions — a run that finished was invisible for nine seconds, and an
idle workspace recomputed everything six times a minute per open tab. The header
always says which state the connection is in (live, polling,
reconnecting, static), because a dashboard that cannot tell you it has lost
the server is worse than one that is plainly offline: the stale numbers still
look like numbers.
Architecture
bin/bb.js the entrypoint
src/ Node, ESM, zero dependencies — every verb, the adapters, the store, the console
skills/ the skills bb wire installs: bb-finish, antislop
kernel/ Rust — bbk: walk, fingerprint, estimate, dupes, symbols, anchor, gate, worktree,
and the scenario runner, the load simulator and the health probe
arc/ Rust — the declaration index compiler. src/arc/read.js is the in-process reader,
which is where the speed-up lands; the binary is the reference implementation
expert/ Python (stdlib) — rule engine, triage, confidence, signals, rules, graph, model, memory,
the world derivation, coverage planning, scenario selection and board verdicts
.bundlebox/ per-repo: config.json, cookbook/ (corpora), genesis/ (world models),
var/ (store, boards, simulations, calibration), out/ (tables, briefs, packs, the page)
The kernel runs a corpus on threads with one connection per worker and a shared
pacer; a 130-step corpus that takes two minutes paced against a real limiter
takes under a second against a local mirror. It speaks http only, because TLS
would be a dependency it must build without — the JavaScript engine runs when
the base is https, when the kernel is absent, or when a corpus uses a pattern
outside the kernel's documented subset, and the board names which engine ran and
why. test/scenario.test.js pins the two to identical answers.
The three runtimes agree by test: test/kernel.test.js and
test/expert.test.js pin the kernel and the expert system to the JS answers.
One implementation per fact where only one runtime has it; parity where two do.
Configuration
One file, .bundlebox/config.json, holding only the keys you changed. Every
default lives in src/core/config.js with its reason. Measured values live in
.bundlebox/var/calibration.json and are written by read-merge.
{
"lanes": { "agent": "claude", "max_parallel": 4, "model": "sonnet", "daily_budget_usd": 20 },
"budget": { "max_tokens": 160000, "churn_factor": 2.4, "anchor_widen": 0.45 },
"kernel": { "gates": { ".": { "quick": "npm test", "full": "npm run lint && npm test" } } },
"detectors": { "promote_at": "medium" }
}
Documentation
- docs/agents.md: integrating bundlebox into every agent, and running work through them
- docs/index.html: the reference site
- EXPLANATION.md: the thesis, the flow, what changed from the original
- whitepaper/bundlebox-whitepaper.md
- docs/review-of-the-original.md: the defects found in the reference implementation
- docs/prices.md: price table provenance
- docs/prior-art.md: seven projects read, what came back and what did not
- CHANGELOG.md and changelogs/
- CONVENTIONS.md: how the code is organised, for contributors
Releases
Tags vX.Y.Z on main build the kernel for five targets, publish to npm with
provenance, and create a GitHub release with the binaries and the changelog.
bb update checks the registry at most once a day; bb update --apply installs.
License
MIT. src/finish/vendor/ is vendored from
Leonxlnx/unlazy 2.1.0 (MIT, commit
1667149), renamed and otherwise untouched;
src/finish/vendor/PROVENANCE.md records every
rename and why nothing else moved. bundlebox began as a stdlib-Python factory wired into one workspace; this
package is its portable core, rebuilt and corrected. The optional wire
integration talks to headroom
over the process boundary and never imports it.