bundlebox

<p align="center"><img src="assets/logo.svg" width="112" alt="bundlebox"></p>

<h1 align="center">bundlebox</h1>
<p align="center"><b>The zero-token software factory for AI coding agents.</b><br>
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.</p>

<p align="center">
<a href="https://www.npmjs.com/package/bundlebox"><img src="https://img.shields.io/npm/v/bundlebox?color=1F7A5C" alt="npm"></a>
<a href="https://github.com/blackswanalpha/bundlebox/actions/workflows/ci.yml"><img src="https://github.com/blackswanalpha/bundlebox/actions/workflows/ci.yml/badge.svg" alt="ci"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-3FB58A" alt="MIT"></a>
</p>

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`):

| | before | after |
|---|---|---|
| opening window per spawned session, before any work | 44.3k tokens | 29.2k tokens (−34%) |
| the same findings, planned | 5 sessions, 1.3M projected | 2 sessions, 351k (−74%) |
| one pipeline tick (`bb pipeline run intake`) | 226 agent turns | 133 s, 0 model tokens |

## Install

```bash
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

```bash
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:

```bash
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.

| agent | instructions | hooks | skills | MCP |
|---|---|---|---|---|
| Claude Code | `CLAUDE.md` | UserPromptSubmit (builds the brief), PreToolUse Read/Grep/Bash (serves it), SessionStart (table index), PostToolUse (the sieve, off until `sieve.enabled`), PreCompact, SessionEnd (the bill) | `.claude/skills` | `.mcp.json` |
| Codex CLI | `AGENTS.md` | — | `.codex/skills` | `.codex/config.toml` |
| Gemini CLI | `GEMINI.md` | — | — | `.gemini/settings.json` |
| Cursor | `.cursor/rules/bundlebox.mdc` | — | — | `.cursor/mcp.json` |
| GitHub Copilot | `.github/copilot-instructions.md` | — | — | `.vscode/mcp.json` |
| OpenCode | `AGENTS.md` | — | — | `opencode.json` |
| Cline / Roo | `.clinerules/bundlebox.md` | — | — | — |
| Windsurf | `.windsurf/rules/bundlebox.md` | — | — | — |
| Aider | `.aider.conf.yml` reads `AGENTS.md` | — | — | — |
| any command | `lanes.custom_command` with `{prompt_file}` `{cwd}` `{model}` | — | — | — |

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:

```json
{ "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:

```bash
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