How Sub‑Agents Keep Claude Code Sessions Clean

What are Sub‑Agents

Sub‑agents are dedicated assistants that run in their own context window, have their own system prompt, tools, and permissions. The main agent invokes them, they complete work in isolation, and return a summary.

You can create a sub‑agent with a Markdown file that contains frontmatter, for example:

---
name: code-reviewer
description: 审核代码的质量、安全性和可维护性。在编写或修改代码后使用。
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是一位高级代码审核员。当被调用时：
1. 运行 git diff 查看最近的更改
2. 专注于修改过的文件
3. 立即开始审核

Claude Code automatically detects such files and calls the sub‑agent when the description matches the task.

Sub‑Agent Location

Files can be stored in different locations based on scope. When two sub‑agents share the same name, the one in the higher‑priority location wins.

Typically you use .claude/agents/ (shared via version control) or ~/.claude/agents/ (personal use).

Problem: One Window Handles Everything

Without sub‑agents, the main agent performs all operations in a single context: reviewing a controller, searching patterns, validating, launching grep, find, ls, glob, cd, and more. Each call remains in the context.

After about thirty minutes you may have 80 k tokens of noise that you will never read.

When Claude compresses the context, these details are flattened and important information can be lost in the summary.

Built‑in Sub‑Agents: Explore and Plan

The two most frequently used built‑in sub‑agents are:

Explore : Searches the codebase without polluting the main context. All grep and find calls run in its own window and only relevant findings are returned.

Plan : Conducts investigation and generates an implementation plan. It reads files, understands architecture, and returns a step‑by‑step document. The main context never sees the intermediate reads; instead of fifty tool calls you receive three lines of answer, the rest being discarded.

Forking Context

By default a sub‑agent starts with a blank context, which keeps things clean but prevents it from inheriting the 100 k tokens you may have already spent building an understanding of the codebase.

Forking solves this: a sub‑agent begins with an exact copy of the parent’s context at the moment of forking.

export CLAUDE_CODE_FORK_SUBAGENT=1

How It Works

When CLAUDE_CODE_FORK_SUBAGENT=1 is set, each sub‑agent automatically inherits the full parent context.

You can also use the /fork slash command to fork on demand.

Forked tool calls remain isolated; only the final result is returned to your conversation.

Characteristics of a forked sub‑agent:

Inherits the entire parent dialogue at the moment of forking

Shares the prompt cache prefix with the parent (sub‑agents 2‑N are about ten times cheaper on input tokens)

Runs in isolation, so its tool calls do not pollute the parent

Returns only the final summary

Real‑Time View: context‑timeline Hook

Tracking the main agent’s context and parallel sub‑agents from the console is difficult. I built a hook called context‑timeline to address this.

Link: https://www.aitmpl.com/component/hook/monitoring/context-timeline

Installation:

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

The hook shows a timeline from the moment you open the session, displaying the main agent’s context window and how each sub‑agent starts work in its own independent context.

Each running sub‑agent is shown in real time, along with the context it returns to the main agent upon completion.

My recommendation: start with a simple sub‑agent placed in .claude/agents/. In your first long session you will immediately feel the difference.