How Subagents Keep Claude Code Context Clean

What Are Subagents

Subagents are specialized assistants that run in independent context windows, each with its own system prompt, tools, and permissions. When the main agent invokes a subagent, the subagent completes its work in isolation and returns a concise summary to the main conversation.

Creating a Subagent

You can define a subagent with a Markdown file that includes front‑matter metadata. Example:

---
name: code-reviewer
description: 从代码质量、安全性和可维护性维度审查代码。编写或修改代码后使用。
tools: Read, Grep, Glob, Bash
model: sonnet
---
你是一名资深代码审查员。被调用时执行以下操作：
1. 执行 git diff 查看近期变更
2. 聚焦已修改文件
3. 立即开始代码审查

Subagent Storage Locations

Save subagent files to different paths based on scope. In most cases use .claude/agents/ (version‑controlled, team‑shared) or ~/.claude/agents/ (personal, global). If multiple subagents share the same name, the higher‑priority path takes precedence.

The Problem with a Single Window

Without subagents, the main agent performs all operations—grep, find, ls, glob, cd—in a single context. Each call remains in the conversation, quickly accumulating up to 80 000 tokens of redundant information that later gets flattened during context compression, causing loss of key details.

Built‑In Subagents: Explore and Plan

Explore : Searches the codebase without polluting the main context; all grep/find actions run in an isolated window and only relevant results are returned.

Plan : Analyzes files, understands architecture, and generates a step‑by‑step implementation plan, keeping intermediate reads hidden from the main context.

Workflow comparison: the original window may show around 50 tool calls, whereas using subagents reduces the visible output to just three lines of final answer, discarding intermediate noise.

Context Forking (FORK_SUBAGENT)

By default subagents start with a blank context, ensuring cleanliness. When a large token investment has already built up knowledge, set the environment variable export CLAUDE_CODE_FORK_SUBAGENT=1 so that new subagents inherit the parent’s full context at launch. The /fork slash command can also copy context on demand.

Forked subagents inherit the parent dialogue, share the prompt‑cache prefix (reducing token consumption for subsequent subagents by roughly tenfold), run independently without contaminating the parent, and return only the final summary.

Real‑Time Monitoring: context‑timeline Hook

Tracking the status of the main agent and parallel subagents is difficult from the console. Install the monitoring hook with:

npx claude-code-templates@latest --hook monitoring/context-timeline

The hook launches at session start, displaying a timeline that shows the main context window and how each subagent operates in its own context, as well as the final content returned to the main agent.

Recommendation

Create a simple subagent in .claude/agents/ and run a long session; you will immediately notice a cleaner context and reduced token waste.