---
title: "Subagents and Context Management"
description: "Preserving root conversation context by dispatching isolated sub-agents for repo exploration, testing, debugging, and file edits."
section: "concepts"
type: "concept"
created: "2026-08-22"
updated: "2026-08-30"
confidence: "high"
tags: ["agents", "subagents", "context-engineering", "workflow"]
canonical: "https://pyweb.dev/wiki/subagents-and-context-management"
---
# Subagents and Context Management

LLM context windows carry token budgets and degrade in reasoning sharpness as conversations grow bloated. Subagents solve this by isolating high-token exploratory work in ephemeral child contexts, returning only concise summaries to the root agent.


```text
dispatch  -> subagent context = goal + minimal files + output schema
collect   -> parent receives result summary only (not the transcript)
```

## Core Roles
- **Exploration (e.g. Claude Code Explore):** An isolated subagent searches the tree, locates relevant views/templates/functions, and hands back exact file paths and line numbers without flooding the root session.
- **Parallel Subagents:** Independent tasks (e.g. updating 5 decoupled template files or refactoring independent modules) dispatched concurrently across child agents to accelerate throughput.
- **Specialist Subagents:** Delegating specific roles like code reviewer, verbose test-runner filter, or debugger to dedicated prompts with customized system instructions.

## Context Preservation Rule
The primary value of subagents is not unnecessary complexity, but preserving the root agent's context window for architectural decisions, high-level verification, and user steering.

## Failure Modes

| Symptom | Root cause | Fix |
|---|---|---|
| Subagent returns useless summary | Goal under-specified at dispatch | Goal = task + files + output schema, written down before dispatch |
| Parent context explodes on collect | Full transcripts merged back | Collect result summaries only; transcripts stay in the subagent |
| Subagents duplicate work | Overlapping scopes | Partition by file/area ownership before dispatch |
| Lost consensus across agents | No synthesis step | One parent-side synthesis pass over all summaries |

## Rule of Thumb

## Rule of Thumb

A subagent gets a goal, the minimum files, and an output schema - never
the parent transcript. If it needs the transcript, the task split is
wrong.

## Related
- [simon willison](/wiki/simon-willison)
- [agentic engineering patterns](/wiki/agentic-engineering-patterns)
- [context engineering](/wiki/context-engineering)
- [karpathy four guidelines](/wiki/karpathy-four-guidelines)

---

## Agent Navigation

cluster: person (170 pages) | betweenness: 157.6

### References (outbound)
- [Simon Willison](https://pyweb.dev/wiki/simon-willison.md)
- [Agentic Engineering Patterns](https://pyweb.dev/wiki/agentic-engineering-patterns.md)
- [Context Engineering](https://pyweb.dev/wiki/context-engineering.md)
- [Karpathy's Four Guidelines](https://pyweb.dev/wiki/karpathy-four-guidelines.md)

### Referenced by (inbound)
- [Agent Containment and Blast Radius](https://pyweb.dev/wiki/agent-containment-and-blast-radius.md)
- [Agent Harness Engineering](https://pyweb.dev/wiki/agent-harness-engineering.md)
- [Agent-Native Infrastructure](https://pyweb.dev/wiki/agent-native-infrastructure.md)
- [DeepSeek Harness](https://pyweb.dev/wiki/deepseek-harness.md)
- [Evals Skills](https://pyweb.dev/wiki/evals-skills.md)
- [Multi-Agent Orchestration](https://pyweb.dev/wiki/multi-agent-orchestration.md)

### Evidence (verified primary sources)
- [simon-willison-subagents-2026](https://pyweb.dev/wiki/raw/articles/simon-willison-subagents-2026.md) | origin: https://simonwillison.net/guides/agentic-engineering-patterns/subagents/ | ingested: 2026-08-22 | sha256: 833ae739f8fe7ace9d7acddf9939cdedf239cf9cef58be91e695cca6a72f6343
- [simon-willison-how-coding-agents-work-2026](https://pyweb.dev/wiki/raw/articles/simon-willison-how-coding-agents-work-2026.md) | origin: https://simonwillison.net/guides/agentic-engineering-patterns/how-coding-agents-work/ | ingested: 2026-08-22 | sha256: 0cd16e1c94ce3427c9f45d34f954ee153ec2fc7ec11fdf416988c79e69aee844

### Machine endpoints
- Knowledge graph: https://pyweb.dev/api/graph.json
- Graph analysis: https://pyweb.dev/api/graph-analysis.json
- Context index: https://pyweb.dev/llms.txt