Subagent
A subagent is a specialized LLM agent spawned by a parent agent to handle a focused subtask with its own prompt, tools, and context window.
A subagent is a specialized LLM agent spawned by a parent autonomous agent to handle a focused subtask. It gets its own system prompt, its own context window, and often a reduced set of tools. When it's done, it returns a concise result to the parent instead of polluting the parent's context with every intermediate step.
Why it matters
The main reason for subagents is context hygiene. If your parent Claude Code agent is doing a big refactor and needs to "find every call site of function X," doing that investigation in the parent fills its context with grep output it will soon forget about. Spinning up a subagent to do the search, read results, and return just "here are the 12 files" keeps the parent focused.
Subagents are also how you package specialized expertise: a "test-writer" subagent with a tuned system prompt, or a "security-review" subagent that only reads and never writes. SpaceSpider users often pair subagents with git worktrees and dedicated spaces to keep each agent's scope clean.
How it works
In Claude Code, subagents are configured in .claude/agents/*.md files or ~/.claude/agents/ for user-level defaults. Each subagent file has:
- A name
- A description (so the parent knows when to delegate to it)
- An optional tool allow-list
- An optional model override
- A system prompt describing the subagent's role
When the parent's LLM decides to delegate, it calls the Agent or Task tool with a prompt. The harness spins up a fresh conversation with the subagent's system prompt, runs the loop, and returns the final message.
Codex CLI, Qwen Code, and other agentic CLIs have analogous features under different names.
How it's used
Common subagent patterns:
- Investigator — "find all X in the repo" — returns a list, not the raw search output
- Reviewer — examine a diff and return a structured review
- Test writer — given a function, produce a test file
- Migrator — rename or convert API calls in one file
A well-decomposed task uses subagents for anything that would blow up parent context but doesn't need the parent's full history.
Related terms
- Autonomous agent — the parent concept
- Context window — why subagents exist
- System prompt — how subagents are specialized
- Tool use — the delegation mechanism
- Slash command — a related reuse pattern
FAQ
Are subagents cheaper?
Sometimes. You can point a subagent at a smaller model (Haiku, mini-tier) when the task doesn't need frontier reasoning. Paying for two cheap subagents is often less than one expensive parent call.
Can a subagent spawn its own subagents?
Typically yes, but most teams avoid deep hierarchies. Two levels (parent + one subagent) covers most needs without debugging nightmares.
Related terms
- Agentic codingAgentic coding is software development where an LLM-powered agent plans, edits, runs, and verifies code on its own using tools, not just autocomplete.
- AI pair programmingAI pair programming is a collaboration style where an LLM assistant sits alongside you, suggesting code and reviewing changes in real time as you work.
- ANSI escape codesANSI escape codes are control sequences that terminals interpret for colors, cursor movement, and screen clearing — the language of every modern CLI UI.
- Autonomous agentAn autonomous agent is an AI program that perceives, decides, and acts on its own toward a goal — the architecture behind modern coding CLIs.
- CheckpointA checkpoint is a saved snapshot of file state that lets you roll back an AI coding agent's changes to a known-good point.
- Claude CodeClaude Code is Anthropic's official command-line agent that plans, edits, runs, and verifies code across your repo using Claude models and tool use.