the cognitive load of running parallel Claude Code agents

Running multiple Claude Code agents at once is technically possible today. claude --dangerously-skip-permissions in as many worktrees as your machine can handle; pipe them tasks from a shared file; let them run in parallel while you context-switch across terminal tabs. Plenty of engineers in the Claude Code ecosystem have made this work.

The problem isn't whether it works. The problem is that as you scale the number of parallel agents, the cognitive load scales faster — and at some point you're spending more energy managing agents than you'd spend writing the code yourself.

This is a look at what that overhead actually consists of, because naming it clearly is the prerequisite for solving it.

1. task decomposition is harder than it looks

The starting point for parallel agents is deciding what to run in parallel. In theory, you decompose a feature into N independent tasks and hand them off. In practice:

• Dependencies are rarely obvious until you hit them. Two tasks might look independent — "add user search endpoint" and "add search results UI" — until the agent building the UI finds that the endpoint's response shape doesn't match what it assumed, and you have to stop, arbitrate, and re-brief one of them.
• Decomposition requires deep upfront context. To correctly split a feature into parallel tasks, you need to understand the full shape of the work first. That's the same analysis you'd do before writing any code — except now you're also responsible for the split.
• The cost of a bad split is high. Two agents that collide on the same files, or build toward incompatible assumptions, don't just slow down — they produce work you have to throw away. This hurts more than doing it sequentially.

Experienced engineers get better at this over time. But decomposition is non-trivial cognitive work, and it happens before the agents start.

2. context is not free to maintain

Each agent needs enough context to do its job without interrupting you — the codebase architecture, the conventions, the decisions already made, the constraints it can't violate. When you're running three to five agents:

• Each agent's context window starts fresh per session (or per worktree, for worktree-based runs).
• If your codebase conventions are in a CLAUDE.md file, that's one problem solved — but the task-specific context for each agent has to be written by you, each time.
• When earlier decisions change — and they do — you have to update every in-flight agent that might be affected. Finding out that an agent has been operating on an outdated assumption for the last 20 minutes is a specific kind of painful.

The more agents you run, the more this maintenance compounds. You're not just writing five task prompts; you're also responsible for keeping five independent contexts coherent with each other and with a codebase that's changing as the agents work.

3. the review burden multiplies

Five agents running for 30 minutes produce roughly five times as much output as one agent. All of it needs review before it lands in your main branch — and review is a high-attention activity that doesn't parallelize well for a single human.

the typical pattern: agents finish faster than you can review them. you end up in a queue — approving agent A's diff while agents B through E are already done and waiting. the throughput gain at the generation stage evaporates at the review stage.

This gets worse when the outputs interact. Reviewing agent A's changes requires understanding how they'll compose with agent B's changes, which you haven't reviewed yet. You're not reviewing five independent units — you're reviewing five pieces of a system that has to fit together.

4. tracking state across agents is a context-switching tax

With multiple agents running, your attention is split. The costs of splitting attention are well-documented in cognitive psychology, but they feel different in practice than the research makes them sound. It's not just "overhead per switch." It's:

• Losing the thread. You intervene with agent B, and when you return to agent A you have to rebuild your mental model of what it was doing and where it is. This happens repeatedly, across every agent, all session.
• Interrupt-driven work. Agents surface questions, hit ambiguities, or produce outputs you need to review — each on their own schedule. You're not working on one thing; you're triaging notifications.
• The illusion of progress. Agents are always doing something, which creates a feeling of high throughput. But if you're spending 60% of your time managing them rather than reviewing shipped work, the throughput is largely illusory.

5. merging is a coordination problem

Git worktrees give each agent an isolated environment to work in. They're the right tool — without them, parallel agents would immediately conflict at the filesystem level. But isolation doesn't make the merge easy, it defers it.

When agents working in parallel worktrees produce changes to related parts of the codebase, merging their work back to a coherent main branch is a sequencing problem you solve manually. For small, truly independent changes (update this config, add this endpoint, fix this test), it's straightforward. For anything that touches shared interfaces, shared state, or related components, you're doing the integration that a careful sequential approach would have avoided.

The harder the merge, the more it erodes the throughput you gained by running things in parallel.

6. the big picture fragments

This is the subtlest cost, and possibly the largest one over a full feature cycle.

When you write code yourself — even with an AI assistant — you hold the whole shape of the change in your head while you work. You notice that the thing you're building in this file contradicts a constraint you set three files ago. You catch the design mistake before it propagates into an implementation mistake.

When you're managing multiple agents, your attention is never fully on any single thread. The agents optimize locally — each one is doing a reasonable job on its assigned task. But the coherence of the whole is something you have to actively maintain, and it competes with everything else you're managing. Features built this way tend to require more rework because the integration assumptions were never held cleanly by any single mind.

---

what this adds up to

The cognitive load of parallel Claude Code agents has roughly four sources:

• Upfront decomposition: the analytical work of splitting tasks correctly before you start.
• Context maintenance: keeping multiple agents coherent with each other and with an evolving codebase.
• Multiplied review: reviewing N agents' outputs faster than they produce them, while accounting for how the outputs compose.
• Fragmented attention: the switching costs of tracking multiple independent threads and the coherence loss that follows.

None of these are unsolvable. Engineers who run parallel agents heavily develop habits that reduce each cost — careful decomposition discipline, rigorous CLAUDE.md files, structured review sequences. But the habits are load-bearing, and if they slip the overhead spikes fast.

what a structured lifecycle does differently

defract's approach to this isn't to eliminate parallelism — parallel agents in isolated worktrees are a core part of the implementation stage. The bet is on changing where the load goes.

The pipeline (scope → design → architecture → implementation → review → release) imposes structure that offloads several of the cognitive costs above:

• Design before build. The design stage forces resolution of the "what exactly are we building" question before agents start building. An agent produces the design, you approve it, and that approved design is the context every implementation agent gets. You decompose into parallel tasks after the design is set, not before — with much better information.
• Agents review agents. The review stage deploys review agents — for types, lint, tests, architecture, security, and UX — so the review burden doesn't land entirely on you. You review intent and sign off on a surface built for that purpose, not raw diffs across five worktrees.
• Enforced gates. Each stage transition is gated. No implementation starts until architecture is reviewed. No code ships until review is passed. The gates encode the sequencing discipline that otherwise lives in your head.
• Persistent context. defract maintains memory of the codebase, the decisions made, and the conventions in play — so each agent starts with current context rather than a fresh context window you fill by hand. (More on keeping context and decisions consistent across parallel agents.)

The parallel agents still run. The worktree isolation is still there. What changes is that the coordination overhead has a structure holding it, rather than being held entirely in your working memory.