Defining a subagent
# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews a diff for correctness, security and test coverage. Use after any non-trivial change.
tools: Read, Grep, Glob, Bash(git diff *)
model: sonnet
---
You are a senior reviewer. Read the staged diff, list concrete defects with file:line,
flag untested paths, and stop. Do not edit files.name is how you call it; description is how Claude decides to call it on its own, so write it as a routing rule ("use after any non-trivial change") rather than a job title. tools restricts what it may do — a reviewer that cannot edit is a safer reviewer. model pins a tier: haiku for scouting and classification, sonnet for most work, opus for the hard step, or inherit to follow the parent session.
Project vs user agents
Files in .claude/agents/ belong to the repository and travel with it — commit them, and every teammate gets the same reviewer, test-writer and migration agent. Files in ~/.claude/agents/ are yours across every project. Project agents win on a name clash. /agents inside a session lists, creates and edits both kinds without touching files by hand.
When Claude delegates
Two ways. Implicit: the main agent reads every subagent's description and delegates when a task matches — "run the code-reviewer subagent on this" is not required if the description already says when to use it. Explicit: name it in the prompt. In both cases the subagent runs in its own context, sees only what it is given plus what it reads, and returns a result the main session summarises into its own history. Subagents do not spawn subagents; the hierarchy is one level deep.
Why they keep sessions cheap
Every turn in Claude Code resends the whole conversation. A subagent that reads forty files does so in its own window; the parent receives a paragraph. Without subagents those forty files would sit in the main context for the rest of the session, resent on every turn. So the pattern for large codebases is: scout with a Haiku subagent, review with a Sonnet subagent, keep the parent's context for decisions. Each subagent bills its own tokens — it is not free, it is contained.
Parallelism and rate limits
Several subagents can run at once, and each is a parallel streaming request. That is the quickest way to hit the concurrent-request limit on any endpoint, so on a new gateway account start with two or three in parallel and ask for higher concurrency once the workload is real. The errors guide covers the 429 you get otherwise.
Agent teams
Newer Claude Code builds add agent teams: instead of one parent delegating to short-lived subagents, several sessions coordinate as named teammates with a shared task list and messages between them, so a lead can hand out work, ask for status and stop a teammate. It is an experimental capability that ships behind a setting and changes between releases — check claude --help and the changelog for the current flag rather than a blog post. The mental model is the same as subagents with persistence and communication added; the cost model is the same too, multiplied by teammates.
On the gateway
Subagents and teams use the same endpoint and key as the parent session, so ANTHROPIC_BASE_URL=https://aiprimetech.io covers all of them. On a flat-rate unlimited plan the parallelism question becomes a fair-use question rather than a billing one, which is why heavy multi-agent users tend to end up there.
| Plan | Duration | Price |
|---|---|---|
| Unlimited 1 Hour | 1 hour | $1 |
| Unlimited 24 Hours | 24 hours | $10 |
| Unlimited 1 Week | 1 week | $49 |
| Unlimited 15 Days | 15 days | $89 |
Frequently asked questions
What is a subagent in Claude Code?
A separate agent with its own system prompt, tool permissions, model choice and context window, defined as a Markdown file in .claude/agents/, that the main session delegates tasks to.
Where is the Claude Code subagents documentation?
The official reference is in Anthropic's Claude Code docs under Sub-agents; this page is the practical version — the file format, when delegation happens and what it costs.
Do subagents cost extra?
They bill their own tokens like any request. They save money on long sessions by keeping large reads out of the parent context, and they cost more if you run many in parallel on Opus.
What are agent teams?
An experimental extension where several Claude Code sessions coordinate as named teammates with messaging and a shared task list, rather than one parent and short-lived helpers.
Run Claude Code on the gateway
Same models, two environment variables, credits at 7.69× face value — or a flat-rate unlimited plan.
Get an API key See unlimited plansAI Prime Tech is an independent API gateway and is not affiliated with, endorsed by, or sponsored by Anthropic. “Claude” and “Claude Code” are trademarks of Anthropic. Claude Code features described here follow Anthropic’s public documentation at the time of writing and change frequently; prices and model lists on this page are read from this gateway’s live settings.