Subagents, parallelism, and worktrees

The last chapter was about dialling how hard the agent thinks. This one is about choosing where it thinks — and how many places at once. Because by now budgetcli has two jobs in front of it that are too big and too noisy to run in your main session as-is, and the move that lets you run them without drowning your context is delegation: a fresh window that does a scoped job off to the side and hands back only the conclusion.

The core idea is small and it carries the whole chapter, so hold onto it. A subagent is a separate Codex session with its own context window. You hand it a task, it works in isolation — reading files, running greps, dumping logs into its memory, not yours — and when it’s done it returns a single summary to your main thread. The hundreds of file reads it did to reach that summary never enter your conversation. You get the destination; the worker eats the journey. That’s the trade in one line, and everything below is learning when and how to make it.

The two jobs in front of you

You inherited budgetcli with three years of imported transaction history and a categorisation taxonomy that has drifted. Two things now need doing, and neither fits comfortably in a single thread:

Recategorise three years of historical transactions against the corrected taxonomy — and refactor the money-handling so every path stores integer cents, never floats.

The first is high-volume and embarrassingly repetitive: thousands of rows, the same judgement applied over and over, pages of output you will never read line by line. The second touches many files at once — every place that parses, stores, sums, or formats money — and you’d like several agents working on it in parallel without tripping over each other’s edits.

Do all of that inline and you bury the actual work — the review, the decisions — under a landfill of file dumps and diffs the agent has to keep carrying. So we’ll do it the other way. Over the next few lessons:

• Push the noisy recategorisation into an isolated subagent and watch what comes back — the summary, not the thousand rows that produced it.
• Fan the recategorisation out across parallel workers when the job splits into independent slices, and learn when that’s leverage versus when it’s just showing off.
• Give each worker its own git worktree so the money-handling refactor 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 handoff, write the aggregation step before you fan anything out.

By the end, “should this happen in my thread or somewhere else?” will be a question you ask before every noisy or parallel task. Start with delegating the recategorisation.