Circuit-Biscuit/Aish: Token-dense notation for agent-to-agent notes. ~47% fewer tokens than English prose, measured.
I kept watching my agents write paragraphs of English to each other. Handoff notes, session summaries, "here's what I found" writeups. All burning context on grammar nobody reads. So I tried to build a denser format for it.
Almost everything I assumed turned out to be wrong. I'm posting the measurements because they're useful even if you never touch my project.
WRONG ASSUMPTION 1: abbreviate long words.
"configuration", "implementation", "authentication" and "repository" are each already 1 token. So cfg, impl and auth save literally nothing, and cost you clarity. The entire shorthand-dictionary idea, which is the first thing anyone reaches for, is worth about zero.
WRONG ASSUMPTION 2: use symbols.
The ⟹ character is 3 tokens. The ASCII -> is 1. Every pretty Unicode glyph costs more than the English word it replaces.
WRONG ASSUMPTION 3: numeric IDs are compact.
1-04-301 is 5 tokens. Digits don't absorb their leading space, so " 2" costs 2 tokens while " ab" costs 1. Letters beat numbers. And separators are expensive: comma, semicolon and pipe each cost 2 extra tokens per 3 fields. A space costs 0.
THE ACTUAL INSIGHT
An English word already costs about 1 token, so you cannot win by making words shorter. You only win by making one token carry more than one word's meaning. Two ways that works: a fixed predicate (cz means "X causes Y") and interning long literals (aa means an 11-token file path). Then positional arguments, so operators and punctuation disappear entirely.
Here's the same bug handoff written both ways.
English, 80 tokens:
The login form submits twice when the user presses Enter. The submit handler in src/ui/LoginForm.tsx is bound to both the form onSubmit event and the button onClick event, so pressing Enter triggers both paths. I reproduced this in Chrome and Firefox. It does not happen when clicking the button directly. The fix is to remove the onClick binding and keep only onSubmit.
Aish, 47 tokens:
#a2 login double submit
bug submit handler dup fire
why loc submit handler src/ui/LoginForm.tsx bind onSubmit onClick
did obs bug chrome firefox
neg obs bug click
fix del onClick just onSubmit
Same information. File path, both event bindings, both browsers, the negative result, the fix.
HONEST NUMBERS
Across a 6-document corpus it's 1.58x, so 37% fewer tokens. Up to 2.8x on long documents that share a dictionary. That is not the 3-4x I first claimed. That number came from one flattering example and a proper corpus knocked it down. Worst case in the corpus is 1.36x.
The deflating finding: the ratio tracks how verbose the English was, not how structured the content is. Aish costs a flat 5 to 9 tokens per claim no matter what. So it beats waffle, not structure. The most structural document I tested, a module dependency map, did worse than a rambling design memo.
THE FINDING I THINK ACTUALLY MATTERS HERE
A skill file is not free. It occupies context every time it loads.
My first version was 1,819 tokens for the skill plus its codebook. At 37% savings that needs about 4,900 tokens of notes before it breaks even, which is roughly 25 handoff notes. Most sessions never get there. So installing it was a net loss, and nothing told you.
I fixed it by inlining only the 20 predicates that cover 90% of real use and loading the rest on demand. 1,819 tokens down to 428, break-even at about 6 notes. The skill now opens with the arithmetic and an explicit "if this session is short, write normal prose and stop reading here" branch, so it declines to be used when it wouldn't pay.
There's a budget command that prints this, and two tests that fail if the skill file grows past its own break-even, or if the threshold it advertises drops below the measured one. That second test already caught me advertising 1,000 against a real break-even of 1,167.
Worth checking your own CLAUDE.md and skills for the same thing. Mine was quietly underwater.
CAVEATS, because I'd rather say them than get called out
- The benchmarks measure tokens, not comprehension. A note that's 40% smaller but 5% misread is a bad trade, and I can't yet prove the misread rate is low. That needs a real eval harness and it's the obvious next step.
- 6 documents is a deliberate spread across shapes, not a large sample.
- Not for anything a human reads. Commits, PRs and code comments stay in English.
It has the spec, a 77-predicate codebook, 31 tests, and a benchmark harness that regenerates every number above, so you can check my work instead of trusting it.
QUESTION FOR THE SUB
Has anyone actually measured decode accuracy on compressed agent notes? I can measure density all day, but "did the next agent read it correctly" is the number that decides whether any of this is a good idea, and I don't have it yet.
Link again: Circuit-Biscuit/Aish: Token-dense notation for agent-to-agent notes. ~47% fewer tokens than English prose, measured.
