Context economics

Where the tokens go when agents run as workers.

This page records what we measured on one real project, what we learned from it, and what we changed in this practice because of it. The rules themselves live in rules/working-rules.md and skills/herdr/SKILL.md. This page explains why they say what they say.

The project

A desktop and web app, built over six days by a lead agent session that wrote briefs and ran hc workers in Herdr panes. The work had milestones (a layout engine, a file round trip, a document model), then a cloud service, a live co-editing core and a browser head. Opus did the algorithms, parsers, security and fix work. Sonnet did the feature and UI slices. Every worker ran with --effort high.

We measured every session from its Claude Code transcript (~/.claude/projects/<project>*/*.jsonl): each assistant message carries a usage block with input_tokens, output_tokens, cache_read_input_tokens and cache_creation_input_tokens.

What we measured

• 155 sessions. 42 of them ended above 280k context.
• About 5.6 billion tokens were read again from the cache. About 28 million tokens were output. Output is under 1% of the tokens processed.

What we learned

1. The cost is the context that each turn reads again, not the output. Every turn sends the whole conversation again. A turn at 280k costs about as much to read as a turn at 30k costs fourteen times over. So the size of the context that a session carries decides its cost far more than how much it writes.
2. Effort is not the lever. Effort changes how much a model thinks and writes. That is the small part of the bill. A higher effort also fills the context faster, which makes the expensive part bigger and makes a worker reach its cap sooner. We kept high.
3. Big briefs cost twice. A brief with four or more deliverables drove a worker to the 300k cap. It stopped with PARTIAL, and a second worker started by reading the first worker’s report and the code again. A brief sized to finish under about 200k avoids both the high context and the second start.
4. The lead was the outlier. A worker has a brief and a cap, so it ends. The lead had neither. It ran for many hours, so its average context per turn (283k) was the highest of all, and it was about a quarter of all cache reads.
5. Waiting in the foreground is expensive. The lead waited for workers with hc wait --children any --timeout 580 in a loop, and for CI with check-ins. hc wait returns on every timeout and on every status change (a worker going idle while its tests run counts). Each return was a lead turn, and each turn read about 280k again, to learn that nothing had happened.
6. The model split was right. The slices that went to Opus (a network-facing parser, a convergence algorithm, auth, a live server room) found and fixed real high-severity defects before anything went live. The Sonnet slices passed in one part or stopped only at the cap. Keep strong models where a mistake is expensive, and use the cheaper model for features.

What we changed

wait-event reads the JSON that hc wait prints: a top-level from is a message; a child with an exit_code, a blocked or error status, or an exit reason is an event. With no live child, hc wait returns at once, so the script sleeps for --every seconds before it asks again. Its tests (skills/herdr/scripts/tests/test_wait_event.py) play a sequence of hc wait answers through a stub hc and check where it stops.

How we judge the two-deliverable size

The first version of the rule said two or three deliverables. On the day it went in, the lead saw briefs with three full deliverables reach the 300k cap, and it moved to about two in its next briefs. A worker costs about 100k before it builds anything: 57k at its first turn and about 100k by its tenth. So each split also has a cost, and too small a brief wastes context too.

The baseline is the 28 worker sessions that started after the lead moved to about two. It is not a clean test of two deliverables: some of those briefs still held three to six work items.

Judge the rule after the next 20 worker sessions on a project that starts with it. Count the work items in each brief first, and leave out a brief that broke the rule.

• Keep it when 2 or fewer of the 20 report PARTIAL at the context cap, and 3 or fewer peak at 280k or more.
• Go back to two or three when the median peak is under 150k and one job needs more workers than the same size of job did before. The briefs are then too small, and the extra start-up cost is the waste.
• Replace it when the briefs keep to the rule and the cap rate stays near 25%. The count is then the wrong measure. Look next at brief size and at the start-up context.

How to measure your own project

Sum the usage blocks of your sessions. A short Python script is enough:

import glob, json

reads = out = turns = 0
for f in glob.glob("<home>/.claude/projects/<project-folder>*/*.jsonl"):
    for line in open(f, errors="ignore"):
        try:
            m = json.loads(line).get("message") or {}
        except ValueError:
            continue
        u = m.get("usage") if isinstance(m, dict) else None
        if u:
            turns += 1
            reads += u.get("cache_read_input_tokens", 0)
            out += u.get("output_tokens", 0)
print(turns, reads / turns, out)  # turns, average context per turn, output

Split it by directory (the lead’s project folder against the worktrees’ folders) and by message.model to see who carries the context. The number to watch is the average context per turn.