davila7/claude_subagents

Claude Code Subagents

Companion repo for the article Keep your Claude Code context clean with Subagents by @dani_avila7.

A hands-on playground to test every subagent scenario: clean context, forked context, and nested chains up to the 5-level depth limit.

The problem

Without subagents, the main agent handles everything in a single context window. Every grep, find, ls, and read stays there — after 30 minutes you have 80k tokens of noise.

Main agent context
├── grep → result
├── glob → result
├── grep → result   ← all this stays forever
├── read → result
└── read → result

Subagents fix this: they work in their own window and return only the result.

Built-in subagents vs custom subagents

Claude Code ships with two built-in subagents:

Custom subagents (.claude/agents/*.md) are project-specific agents you define yourself — they handle things the built-ins don't know about: your domain, your file structure, your conventions.

How subagents invoke other subagents

A subagent calls another subagent via the Agent tool — an explicit tool call, not natural language or a slash command. To enable this, Agent must appear in the subagent's tools frontmatter:

---
name: my-orchestrator
tools: Read, Grep, Agent   ← required to spawn child subagents
model: claude-sonnet-4-6
---

Omitting Agent from tools prevents the subagent from spawning any children.

Scenario 1 — Main agent (noisy context)

Ask the main agent directly, without delegating:

trace which components depend on formatNumber in utils.js

Watch grep/glob/read pile up in your context. Every tool call stays permanently.

Scenario 2 — Clean SubAgent (blank context)

Delegate to a custom subagent. It fires all tool calls in its own window and returns only the result:

use the dependency-tracer to find what depends on formatNumber

use the ui-auditor to check index.html and main.css for accessibility issues

use the style-sync agent to verify the CSS tokens are consistent

Your main context receives one clean summary — not 20 tool calls.

Scenario 3 — Fork SubAgent (inherited context)

By default, subagents start with a blank context. Fork mode changes this: the subagent inherits the full parent context at the moment of the fork.

# Set before opening Claude:
export CLAUDE_CODE_FORK_SUBAGENT=1
claude

Or fork on demand inside a session with /fork.

What the fork gives you:

• Subagent inherits the parent's full conversation at fork time
• Shares the prompt cache prefix → children 2-N are ~10x cheaper on input tokens
• Subagent's tool calls still run in isolation — only the final result returns

Try it:

# Build some context first:
read utils.js and explain what each function does

# Then fork-delegate:
use the dependency-tracer to trace what depends on clamp

Scenario 4 — 5-level nested chain + depth limit

Claude Code allows subagents to spawn their own subagents, up to 5 levels deep. At depth 5, the Agent tool is not provided — the chain cannot go further.

This repo includes a full 5-level chain that triggers automatically from one prompt, plus a depth-limit-tester at level 6 to observe what the API does when the limit is hit.

main agent
  └── project-auditor      (depth 1) — orchestrates the full audit
        └── structure-checker  (depth 2) — verifies all files exist and are linked
              └── import-validator   (depth 3) — validates every import resolves to a real file
                    └── dependency-tracer  (depth 4) — traces what depends on formatNumber
                          └── style-sync         (depth 5) — checks CSS token consistency
                                └── depth-limit-tester (depth 6) — what happens here?

Trigger the full chain:

use the project-auditor to run a full audit of the project

Watch 5 levels open in the subagent panel in cascade. The depth-limit-tester at level 6 lets you observe the raw API behavior — whether it receives the Agent tool, gets silently blocked, or produces an error.

Agents in this repo

Standalone agents

Nested chain agents (Scenario 4)

Where subagents live

Priority (high → low):

1. .claude/agents/    ← this repo (shared with team, version controlled)
2. ~/.claude/agents/  ← personal, available in every project

When two subagents share the same name, the higher-priority location wins.

Demo project structure

The source code is split across folders on purpose — so subagents have real cross-folder work to do.

src/
├── index.html              ← open directly in the browser, no build step
├── styles/
│   └── main.css            ← dark/light theme, CSS custom properties
├── scripts/
│   ├── app.js              ← entry point, mounts components
│   └── utils.js            ← formatNumber, clamp, debounce  ← subagents target these
└── components/
    ├── counter.js          ← imports formatNumber + clamp from ../scripts/utils.js
    └── theme-toggle.js     ← imports formatNumber from ../scripts/utils.js

formatNumber is intentionally imported in two different components — a concrete target for dependency-tracer to chase across folders, and for the nested chain to trace end-to-end.

open src/index.html        # macOS
xdg-open src/index.html    # Linux
start src/index.html       # Windows

Context timeline hook (optional)

Visualize the main context and all subagent contexts in real time:

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

Shows a live timeline of:

• The main agent's context window growing
• Each subagent opening its own isolated window
• The result landing back in the main agent when each subagent finishes

Creating your own subagent

---
name: my-agent
description: What this agent does and when to invoke it. Claude matches tasks to agents via this description.
tools: Read, Grep, Glob, Bash
model: claude-sonnet-4-6
---

You are a specialized assistant. When invoked:
1. Do X
2. Do Y
3. Return only the result, not everything you read

Add Agent to tools if you want this subagent to be able to spawn its own children.