Token Economics

What Headbox costs in tokens and what it plausibly saves, with every number labelled measured, estimated or unproven. The cost figures on this page are measured by the site build from the shipped CLI, so they move when the product does.

The honest summary

The cost is small, mechanical and measured: about 1,515 tokens a session for the rules block, and more only for plugins an agent chooses to read. The token savings are directionally real but estimated. The best evidenced claim is not about tokens at all: Headbox turns "the agent should remember" into an append-only file or a hook that fires anyway.

1,515

Tokens, rules block

Plugins measured

27,125

Tokens, all plugins

Claims

The Claims

Seven claims, each with its evidence and the caveat that limits it. Measured means the number comes from files in this repository. Estimated means it is inferred.

The always-loaded rules block is small and fixed Measured

A fresh install writes 5,768 characters into AGENTS.md and a 293 character import stub into CLAUDE.md. That is about 1,515 tokens, loaded once per session whatever the task.

headbox init into an empty folder, measured by this build

Honest caveat

Characters are converted at roughly four per token, an approximation and not a tokenizer count.

Reading every plugin costs far more than the block Measured

Reading all 27 plugin bodies once is 108,498 characters, about 27,125 tokens. The three largest (parallel-development, autonomy-tiers, agent-roster) are about 7,718 tokens together. The five smallest are about 1,553.

plugins/REGISTRY.md Source column, sizes measured by this build

Honest caveat

Assumes every body is read in full each session. Plugins are opt-in, and a harness that caches may pay less.

The per-prompt reminder is the cost that compounds Measured

The opt-in reinforce hook re-injects the first five rules on every prompt, about 167 tokens each. Over 100 prompts that is about 16,700 tokens. It is off by default. Separately, the default SessionStart hook re-injects the same five rules once when a session resumes or is compacted, about 167 tokens each time.

cli/headbox.js: reinforceHookScript, measured 2026-07-26 against the v0.8.0 rules

Honest caveat

Not re-measured at v0.23.2. The mechanism is unchanged, the rule text may differ slightly.

A generated workspace map is far cheaper than scanning the tree Estimated

In the first study (2026-07-26) the generated workspace map for this repository was 1,306 characters, about 326 tokens, against roughly 6,000 tokens for a recursive listing of its 698 entries. That is the roughly 18x figure.

.headbox/workspace-map.md; tree side modeled; not re-measured at v0.23.2

Honest caveat

The map side was measured, the tree-scan side was modeled, and agents rarely scan an unfiltered tree, so the real ratio is smaller. A fresh install starts with a near-empty map, so this build does not re-measure it.

Guards cost no model tokens to run Measured

The push and destructive-command guards are small Node scripts that read the tool call from stdin and answer allow or deny. No model call is made, so enforcement costs nothing per invocation.

.headbox/hooks/ in a fresh install

Honest caveat

The saving from a blocked bad push (an estimated 2,000 to 8,000 tokens of diagnosis and recovery) is an estimate, and no incident has been logged and measured.

Instructions that depend on remembering rot Observed

In internal sweeps in July 2026, notes files that agents were told to keep up to date had not been touched for six weeks or more, in more than one workspace. Headbox answers with append-only artifacts and hooks that fire whether or not the agent remembers.

internal sweep, 2026-07-25; not reproducible from this repository

Honest caveat

This is evidence about prose-only instructions, not a measurement of Headbox itself.

Break-even takes a few avoided mistakes per session Estimated

Without the reinforce hook a typical session carried roughly 3,400 to 3,900 tokens of Headbox in the first study. Each rediscovered fact costs 500 to 3,000 tokens, so it takes between two and eight of them, or one blocked bad push that would have cost a costly recovery, to pay that back.

cost side measured above, savings side from the first study (2026-07-26)

Honest caveat

This is the weakest claim here. The savings side is estimated, not measured, and the typical-session figure predates the current block size.

What Is Not Instrumented Yet

Claims tagged unproven but instrumentable. None of these six measures exists end to end today, so the follow-through benefit is argued, not counted.

📏

Sessions that end with a commit Not available

Needs a SessionEnd check of git log against session start.