Agent Hierarchies in Claude Code

A single Claude Code session works well for focused tasks. But real projects have dozens of interconnected tasks across multiple files, services, and repositories. Agent hierarchies let you break complex work into coordinated sub-tasks, each handled by a dedicated agent.

How hierarchies work

Claude Code can spawn sub-agents — child Claude Code instances that handle specific parts of a larger task. The parent agent coordinates the work:

  1. The parent agent receives a complex task (e.g., "Add user authentication to the app")
  2. It breaks the task into sub-tasks (middleware, login UI, database schema, tests)
  3. Each sub-task is delegated to a child agent with specific instructions
  4. Child agents work independently, returning results to the parent
  5. The parent reviews, integrates, and verifies the combined result

Why use hierarchies

  • Larger context capacity — Each child agent gets its own context window. A parent with four children effectively multiplies available context.
  • Parallel execution — Independent sub-tasks run simultaneously, completing the overall task faster.
  • Specialisation — Each child can be given a specific skill or persona. One focuses on security, another on testing, another on UI.
  • Isolation — If a child agent fails or goes off-track, it doesn't corrupt the parent's state. The parent can retry or take a different approach.

Delegation patterns

Research and implement

The parent delegates research to one child ("find all the places we handle authentication") and implementation to another ("add JWT middleware following this pattern"). Research informs implementation without overwhelming a single context.

Parallel feature branches

Each child works on a separate feature branch. The parent creates the branches, assigns tasks, and merges results. This mirrors how human teams work with git.

Review chain

One child writes the code, another reviews it. The parent mediates disagreements and makes final decisions. This creates an internal quality gate before human review.

Specialist delegation

The parent identifies what expertise each sub-task needs and delegates accordingly. A database migration goes to a child with DBA-focused instructions. UI work goes to a child with frontend expertise. Testing goes to a QA-focused child.

Practical considerations

Cost implications

Hierarchies use more tokens than a single session because the parent and each child consume their own context. A three-level hierarchy with four children per level can be 10-20x more expensive than a single session. Use hierarchies for genuinely complex tasks, not for simple ones.

Coordination overhead

The parent agent spends tokens summarising, delegating, and reviewing. Keep hierarchies shallow — two levels (parent + children) is usually optimal. Three levels add more coordination overhead than they save.

Error handling

Child agents can fail, produce incorrect results, or exceed their token budget. The parent should:

  • Verify child output before integrating it
  • Have a fallback strategy if a child fails (retry, simplify, or handle manually)
  • Set token limits on child agents to prevent runaway costs

When to use hierarchies vs. sequential tasks

  • Use hierarchies when sub-tasks are independent and can run in parallel, or when the total context would exceed a single session's capacity.
  • Use sequential tasks when each step depends on the previous one, or when the task is small enough for a single session.
  • Start simple — Most teams should master single-session usage before attempting hierarchies. Hierarchies add power but also complexity.

Next steps

Hierarchies benefit from centralised logging (track what each child agent did), guardrails (enforce boundaries at every level), and shared communication (give the team visibility into what the hierarchy is doing).