.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Ask Claude Code to hunt down every caller of a deprecated function in a large repo and watch what happens to your session: dozens of file reads and greps pile into the context window, and by the time the answer arrives, the conversation is carrying thousands of tokens of search debris it will drag along for the rest of the session. Subagents exist to stop that. A subagent runs in its own isolated context, does the messy work there and hands only the result back to the main loop. The debris stays behind and gets thrown away.
That's the entire idea, and it's a good one. This guide covers the built-in agents, writing your own in .claude/agents/, the delegation mechanics and my honest read on the experimental agent teams feature. Everything tested on Ubuntu 24.04 with the 2.1 line of the CLI; check yours with claude --version.
Built-in subagents: Explore, Plan and general-purpose
Claude Code ships with a few agents and already delegates to them on its own. Explore is a fast, read-only agent for codebase reconnaissance, and you'll see it fire when you ask questions like "where is rate limiting implemented?". It can't write anything, which makes it cheap to trust. Plan does the research legwork when you work in plan mode, and general-purpose is the flexible one for multi-step tasks that need full tool access.
You don't configure any of this. The value of knowing they exist is reading session output correctly (that "Task" entry spinning away is a subagent) and calibrating what your own agents should look like. Anthropic's own split is instructive: each has a narrow job and the minimum permissions that job needs.
Create a subagent in .claude/agents
A custom subagent is one markdown file with YAML frontmatter. Project agents live in .claude/agents/ and get committed so the whole team shares them; personal ones live in ~/.claude/agents/ and follow you across projects. Here's a code reviewer I keep in most repos, at .claude/agents/code-reviewer.md:
---
name: code-reviewer
description: Reviews staged changes for bugs, missing tests and convention
violations. Use proactively after completing a feature or before a commit.
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 25
---
You are a strict code reviewer for this repository.
Process:
1. Run `git diff --staged` (fall back to `git diff main...HEAD`) to see the changes.
2. Read every modified file in full, plus its tests.
3. Check against the conventions in CLAUDE.md.
Report findings ranked by severity. For each: file, line, the problem,
a concrete fix. Flag any changed behavior with no test covering it.
If the diff is clean, say so briefly. Do not suggest stylistic rewrites
of code the diff doesn't touch.The frontmatter fields do the interesting work. name and description are required, and the description matters more than it looks: the main agent reads it when deciding what to delegate, so "Use proactively after completing a feature" is an instruction to the router as much as documentation for you. tools restricts the agent to a subset (my reviewer can read and grep but never edit, on purpose). model picks the brain per agent, so a mechanical test-runner can ride a cheaper model like haiku while the reviewer gets sonnet.
Beyond those, the frontmatter accepts permissionMode (run the agent under a different permission posture than the main session), isolation: worktree (execute in a separate git worktree, so file changes land in their own branch-like sandbox instead of your working tree), background and maxTurns. That last one is my favorite boring field. An agent with a vague task and no turn cap will happily burn twenty minutes going in circles; a cap of 25 turns converts "runs forever" into "comes back and tells you it couldn't finish".
After creating the file, restart the session or start a new one so the agent registers, then confirm it's picked up by asking Claude to list its available agents.
Delegate work to a subagent
Delegation happens four ways. Natural language is the default: say "use the code-reviewer subagent on my staged changes" and the main loop spawns it. Claude also delegates unprompted when a task matches an agent's description, which is exactly what a well-written description buys you. For explicit targeting, @-mention the agent by name in your prompt. And to make an agent the whole session, launch with claude --agent code-reviewer, handy in scripts and CI where you want the specialist and nothing else.
Foreground is the default mode: the main conversation waits for the subagent's report. Setting background: true in the frontmatter (or asking Claude to run something in the background) lets the main loop keep working while the subagent grinds away, with results delivered when ready. Background agents pair nicely with long test suites. I'll kick off a test-runner in the background, keep refactoring in the foreground and get the failure report dropped into the conversation a few minutes later. If you run sessions on a remote box, long background work is also the strongest argument for hosting the agent somewhere that stays up; a Claude Code VPS deploys in about a minute and keeps overnight agent runs alive without your laptop's lid being involved.
Subagent vs skill vs plain prompt
Three tools get confused here, and the distinction is practical rather than academic. A plain prompt is right when the task is small and its intermediate steps are cheap; delegation has overhead (the subagent starts cold with none of your conversation's context) and wrapping a two-minute edit in an agent is pure ceremony. A skill is packaged instructions injected into the current conversation: same context, same history, just expertise loaded on demand. A subagent is the opposite: isolated context, no access to your conversation history and only its report comes back.
So the deciding question is what the intermediate output is worth. Search-heavy exploration and bulk review passes produce middle steps that are pure noise, so isolate them in a subagent. A procedure where every step builds on your session state (a deploy checklist, a styled refactor): keep it in-context as a skill or prompt. Getting this wrong in the subagent direction is worse, in my experience, because a delegated task that needed conversation context comes back subtly wrong and confident about it. The subagents documentation has the full field reference when you're deciding how much rope to give each one, and instructions both levels share belong in CLAUDE.md, which subagents load too.
Agent teams: Experimental multi-agent sessions
Subagents are workers reporting to one session. Agent teams go a step beyond: several independent Claude Code sessions sharing a task list and messaging each other, coordinating like a tiny dev team. It's experimental and off by default; enable it with:
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1The split-pane display needs tmux or iTerm2 (there's a teammateMode setting for how teammates render), it doesn't work in -p print mode, and the agent teams documentation is upfront about the rough edges you'd expect from a feature behind an environment variable.
My take, having played with it: genuinely fun and occasionally useful, but overkill for most daily work. Where it earns space is embarrassingly parallel jobs with little shared state, like migrating forty near-identical modules or churning through a bug backlog where the fixes don't touch each other. For anything with sequential dependencies, one session with well-built subagents beats a team, because teammates working from the same task list can and do step on each other's changes. Watching three agents negotiate over a shared file is entertaining exactly once. Start with a single code-reviewer agent instead; it's twenty lines of markdown, it pays off the first time it catches an untested branch and it teaches you what to delegate before you scale up. Where sessions themselves fit into all this, including resuming and branching them, is covered in our guide to Claude Code sessions.
