Subagents, parallelism, and worktrees

Picture a job whose real work is one decision, preceded by a lot of noisy reading: greps across a codebase, probe runs, files opened and dismissed. Run it in your main conversation and every one of those reads lands in your context window, next to the decision you actually came to make. This chapter’s running example is exactly that job: in budgetcli (the course’s small Python teaching repo), the amount parse in app/importers/csv.py still routes money through a float, and proving the money path clean end to end takes greps, probes, and dead-end reads before anyone writes the fix.

The problem that reading creates is not amnesia. Within a session, context persists, and the rules file loads at start. The problem is real estate. Done inline, every probe and rejected path sits in your window. Pile enough of that debris and it buries the decision, no matter how good the model or how high the effort.

The trade this chapter argues

A subagent is the way out: work dispatched to a separate agent thread with its own context, which does the reading and hands back only what you asked for. Your window receives the return and nothing else - the greps, the probes, and the rejected paths stay in the child. One mental model deserves killing early: the child’s work is not erased the moment it finishes. The trail simply never enters your context on its own.

The real lifecycle is more forgiving than that. In the CLI, /agent switches between active agent threads so you can open one and inspect it; a finished worker stays listed with its result until you close it, steering a worker that is still running is a normal request, and closing a completed thread is something you ask for explicitly. Isolation is real. Erasure is not the model. Reaching the trail is a choice you make, not a door that shut.

Now the honest arithmetic, on this repo’s real sizes. The paths money touches - app/importers/csv.py at 23 lines since the categorizer wiring, app/models.py at 24, app/services/ledger.py at 18, and app/main.py with its endpoints - total about 100 lines, roughly 1,000 estimated tokens at ten per line. A sweep of them returns a findings block of roughly a hundred tokens. Ten to one, read to return; widen the read to the whole repo’s 2,000 and it approaches twenty to one. That ratio is the entire case for isolation.

Be equally honest about the absolute numbers: 1,000 tokens is half a percent of a 200,000-token window. At this repo’s size, delegation buys you quiet and a habit, not a rescue. The reason to run it properly anyway is that the procedure, priced here on numbers that are real, is the same procedure you will need on a codebase where the reading is not pocket change. (Estimators as defined in the first chapter.)

Isolation is a real answer to a real problem, and it charges rent you don’t see until you go looking for it.

The two jobs in front of you

Only one of the two jobs ahead is real at this repo’s scale. The real one is the audit: a read-only sweep of every path that parses, stores, sums, or formats money - the CSV parse, the amount_cents field, the balance arithmetic, the endpoints that serve them - establishing which paths are clean and which still carry the float. It goes to a subagent in the next lesson, and its findings drive everything after.

The second job is the hardening fan-out: several workers editing in parallel, each in its own git worktree, merged back through a review gate. This one is a constructed projection, labeled as such from here on. The sweep will find exactly one live violation, because that is all this repo has; ten files do not need three workers editing at once.

We run the full parallel procedure anyway - the same findings list at the size where it has a line per path - because the procedure is what transfers. The edit that lands through it is real.

Over the next four lessons:

• Delegate the noisy audit to an isolated subagent, price what it read against what it returned, and learn what you can still reach after the answer comes back.
• Fan the remaining audit slices out across parallel workers once you have checked the job actually splits cleanly - and see what fanning out costs that one worker did not.
• Give each worker its own git worktree so the hardening can have several agents editing at once without reading each other’s half-written files.
• Coordinate the workers and merge the results with light orchestration - gate every hand-off, and find out exactly why the merge tail does not shrink just because the fan-out was wide.

By the end, “should this happen in my thread or somewhere else?” will be a question you ask before every noisy or parallel task, with a real ratio behind the answer instead of a hunch. Start with delegating the audit.