Claude Code subagents: delegate tasks and keep your context clean

Claude Code subagents help when a side task floods the main conversation: a test run with a long log, a search across a big repository, a diff review. The subagent does that work in its own context window and sends only the result back to the main session. Below are the file format, the ways to invoke a subagent, and how to pick a model. Everything was checked against the official Claude Code subagents page.

What a Claude Code subagent is

A subagent is a specialized assistant with its own system prompt, its own tool set, and a separate context. The main agent hands it a task, the subagent works on its own and returns the result.

Key properties:

• a subagent does not see the main conversation history. It gets its own system prompt, basic environment details, and a task message that Claude writes;
• a subagent sends its own model requests, so it does spend tokens, but it doesn't bloat the main context;
• Claude decides when to delegate based on the subagent's description field.

Claude Code ships with built-in subagents: Explore (fast read-only search and code reading), Plan (research in plan mode), and general-purpose (complex multi-step tasks that may change files).

Where subagents live

Project subagents are worth committing so the whole team can use them. When names collide, the higher-priority source wins. Claude Code watches these folders and picks up new or edited files without a restart. You only need to restart when the agents folder didn't exist when the session started.

Subagent file format

A subagent is a Markdown file with YAML frontmatter. The frontmatter holds the settings and the body becomes the system prompt.

---
name: code-reviewer
description: Reviews code changes for bugs, security issues and readability. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer. When invoked:
1. Run git diff to see recent changes.
2. Focus on modified files.
3. Report issues grouped by severity: critical, warning, suggestion.
Include a concrete fix for every critical issue.

Only name and description are required. Useful optional fields:

• tools — allowed tools. If you leave it out, the subagent inherits every available tool;
• disallowedTools — tools to remove from that list;
• model — the model (see below);
• permissionMode — permission mode: default, acceptEdits, plan, dontAsk, and others;
• maxTurns — step limit after which the subagent stops;
• mcpServers, hooks, skills — MCP servers, hooks and skills scoped to this subagent;
• isolation: worktree — run in a temporary git worktree instead of your checkout.

Field names are camelCase. Claude Code silently ignores fields it doesn't recognize, so a typo in maxTurns won't raise any error. There is no context-size field.

How to invoke a subagent

1. Automatically. Claude delegates on its own when a task matches the description. Adding "use proactively" to the description encourages it.
2. By name in your prompt: "Use the code-reviewer subagent to check my recent changes". Claude still decides.
3. With an @-mention. Type @ and pick the subagent from the typeahead, or write @agent-code-reviewer. This guarantees that subagent runs.
4. The whole session as the subagent: claude --agent code-reviewer. The main thread takes that subagent's system prompt, tools and model. The "agent": "code-reviewer" setting in .claude/settings.json does the same for a project.

There is also the fork: /subtask followed by a task (versions 2.1.161 to 2.1.211 called it /fork). Unlike a regular subagent, a fork inherits the whole conversation so far, runs in the background, and returns its result as a message. Its first request reuses the main session's prompt cache.

Subagents can spawn their own subagents, up to three levels deep by default. Change the limit with CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH; a value of 1 turns nesting off.

Choosing a model and connecting to Zukko

The model field accepts an alias (sonnet, opus, haiku), a full model ID, or inherit for the main session's model. Resolution order: a model passed with that specific invocation, then the file's model, then the CLAUDE_CODE_SUBAGENT_MODEL variable, then the main session's model.

Through a gateway, inherit or a full ID from the Zukko list is the safer choice: claude-sonnet-5 or claude-opus-5-5. Aliases resolve to specific versions that may not be on the gateway's list. If you do want aliases, redirect them with ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL and ANTHROPIC_DEFAULT_HAIKU_MODEL.

Connecting Claude Code to Zukko:

export ANTHROPIC_BASE_URL=https://api.zukko.pro
export ANTHROPIC_AUTH_TOKEN=fetch_your_key
export ANTHROPIC_MODEL=claude-sonnet-5

The base URL has no /v1. Details are in the Claude Code guide↗. For the current model list, call GET https://api.zukko.pro/v1/models or open the Models page in your dashboard.

What subagents cost

In Zukko, claude-sonnet-5 and claude-opus-5-5 cost the same: $0.3 per 1M input tokens and $0.3 per 1M output tokens. So the model you pick for a subagent is a question of quality on your tasks, not price. Try both on a few real tasks and keep the one that does better.

The saving from a subagent is in the size of the main context. Say a subagent reads 200,000 tokens of logs and code and returns a 2,000-token summary.

• Subagent spend: 200,000 × $0.3 / 1,000,000 = $0.06 for input, plus its output tokens.
• The main conversation gets 2,000 tokens instead of 200,000, so every later turn of the main session sends less context.

A subagent starts with a clean context and sometimes has to re-read files the main session already saw. For small edits, staying in the main conversation is cheaper and faster. One more caveat about caching: vendors charge about 10% of the input price for prompt-cache reads, while Zukko bills cached tokens at the normal input price. So for long agent sessions the real gap versus official pricing is smaller than a straight price comparison suggests. A separate key with a daily limit, created in your dashboard↗, keeps spend under control.

Practical tips

• Keep description narrow: Claude uses that text to decide whether to call the subagent.
• Restrict tools. A reviewer needs Read, Grep, Glob; a test writer needs Edit and Bash.
• Ask the subagent, in its prompt, for a short summary in a fixed format. Everything it returns lands in the main context.
• Running several subagents in parallel makes sense when the investigations don't depend on each other. Keep in mind that each one spends its own tokens.

FAQ

Is there a command to create a subagent?

In current versions /agents just reminds you to ask Claude to create one or to drop a file into .claude/agents/ or ~/.claude/agents/. Older versions (up to 2.1.197) had an interactive wizard.

Does a subagent get my CLAUDE.md?

Yes, custom subagents load CLAUDE.md unless their frontmatter sets omitClaudeMd: true. The built-in Explore and Plan skip it.

How do I see which model a subagent runs on?

/tasks shows the model on the running subagent's row.

Can I stop Claude from spawning subagents?

Yes. Block a specific type with permissions.deny, or deny the Agent tool to block them all.