Claude Code subagents: how to set them up and what they cost

Claude Code subagents are helpers that Claude hands a side task to. Each one works in its own context window with its own instructions, tools and permissions, and only its result returns to your main conversation. You define one in a Markdown file under .claude/agents/, and on an API key its requests are billed per token like any other.

What is a Claude Code subagent?#

Anthropic describes subagents as "specialized AI assistants that handle specific types of tasks." Use one when a side task would flood your main conversation with search results, logs or file contents you won't need again. The subagent does that work in its own context and hands back a short result.

Claude decides when to delegate from your request and from each subagent's description field, so the description matters more than the name. A phrase such as "use proactively" in it encourages Claude to delegate without being asked.

Which subagents come built in?#

• Explore: a fast, read-only subagent for finding files and searching code.
• Plan: a read-only research subagent that Claude uses in plan mode before it proposes a plan.
• General-purpose: has every tool, for complex research, multi-step work and code changes.

Explore and Plan start without your CLAUDE.md files, which keeps research fast and inexpensive. A subagent of your own named Explore replaces the built-in one, and CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 removes Explore and Plan altogether.

How do you create a subagent?#

A subagent is a Markdown file with YAML frontmatter. Only name and description are required, and the text below the frontmatter becomes its system prompt. Where you save the file sets who can use it:

• `.claude/agents/` in your project: this project only. Commit the folder so your team shares it.
• `~/.claude/agents/`: every project on your machine.
• The `--agents` flag: a JSON definition for the current session only.

This reviewer reads code and reports problems without changing anything:

---
name: code-reviewer
description: Reviews code for bugs, security issues and readability. Use proactively after code changes.
tools: Read, Grep, Glob
model: inherit
---
You are a code reviewer. Read the changed files, then list concrete
problems with file and line, most serious first. Don't edit files.
Keep the report short.

You can also ask Claude to write the file for you. Claude Code picks up changes in both folders within a few seconds. Restart it after you create an agents folder that didn't exist when the session started, after you add or edit a subagent in a directory added with --add-dir or /add-dir, or if the session started with --disable-slash-commands.

How do you run a subagent?#

• Ask for it: "Use the code-reviewer subagent to check my last change."
• Mention it: type @ and pick the subagent, or type @agent-code-reviewer.
• Run a whole session as it: claude --agent code-reviewer gives the main thread the subagent's prompt, tools and model. Set "agent": "code-reviewer" in .claude/settings.json to make that the project default.

Subagents that Claude starts from the main conversation run in the background, so you can keep working. Their permission prompts appear in your main session with the subagent's name on them, and /tasks lists the running subagents and the model each one uses.

Which frontmatter fields matter most?#

• `tools` and `disallowedTools`: an allow-list and a deny-list. Leave tools out and the subagent gets every tool.
• `model`: an alias such as sonnet or opus, a full model id, or inherit for the main conversation's model.
• `maxTurns`: a cap on the subagent's turns.
• `effort`: how much the subagent thinks, from low to max.
• `isolation: worktree`: runs the subagent in a temporary git worktree, so its edits don't touch your working copy.
• `permissionMode`, `skills`, `mcpServers`, `hooks` and `memory`: its permission mode, preloaded skills, its own MCP servers, hooks that run only for it, and notes kept across sessions.

Which model does a subagent use?#

Claude Code picks the model in this order:

1. A model alias that Claude names when it starts that subagent.
2. The model field in the subagent's file.
3. The CLAUDE_CODE_SUBAGENT_MODEL environment variable.
4. The main conversation's model.

Set CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (version 2.1.257 or later) to make the variable win over every model field. Aliases move to newer models over time, so pin a subagent with a full model id. Through a gateway, pick an id the gateway serves, since it rejects models it isn't set up for. These are the newest Claude models for Claude Code, at our price per million tokens:

Every model that runs in Claude Code is on the Claude Code setup page.

How to run subagents on a 5abeer key#

Subagents use the main session's base URL and key, so once Claude Code runs on a 5abeer key, every subagent does too:

1. 1

   Top up your balance#

   Pay with one of the payment methods. Every subagent request is deducted from this balance.

2. 2

   Create a key for Claude models#

   Create a key for the Anthropic provider, as in Create a key. Name it claude-code so its usage is easy to find.

3. 3

   Add the settings#

   Put these settings in ~/.claude/settings.json, and replace YOUR_5ABEER_API_KEY with your key:

   settings.jsonmacOS / LinuxWindows

   Copy

   {
     "env": {
       "ANTHROPIC_BASE_URL": "https://api.5abeer.ai",
       "ANTHROPIC_AUTH_TOKEN": "YOUR_5ABEER_API_KEY",
       "ANTHROPIC_MODEL": "claude-sonnet-5.5"
     }
   }
   

   ~/.claude/settings.json

4. 4

   Check a subagent#

   Start claude in your project and ask "use the Explore subagent to find where we parse dates". Run /tasks while it works to see the subagent and its model.

With a 5abeer plan that includes Claude Code, the 5abeer AI app sets Claude Code up with no key, as in Claude Code setup, and subagents run within the plan's limits.

What do subagents cost?#

Moving work into a subagent doesn't remove its cost. Anthropic's docs say that "each subagent spends tokens of its own while it runs": it starts fresh, reads the files it needs and sends its own turns. The saving is in the main conversation, which carries only the short result into later requests instead of everything the subagent read.

For example, a review subagent that reads 400,000 tokens over its turns and writes 20,000, on the default model:

The same job on the newest Opus, claude-opus-5.5:

Five reviewers in parallel cost about five times as much. Give Claude Code its own key with a spend limit, as in Control every key, and check it in Track your usage. Our price next to the official one is on the Claude API page, and The cheapest way to use Claude Code compares a key with a plan.

How to keep subagents cheap#

• Give each one a narrow job. "Find where we parse dates" reads far fewer files than "review the whole repository".
• Keep descriptions short. Every description loads into the main context, and Claude Code warns at startup when yours pass 15,000 tokens together.
• Limit the tools and turns. A reviewer with Read, Grep, Glob and a maxTurns cap can't start long command runs.
• Ask for a short result. It joins the main conversation and is sent again with every later request.
• Use a strong model only where it pays. Set model per subagent instead of running every one on Opus.
• Fork when the task needs your context. /subtask forks the current conversation, and the docs say "a fork costs less than a fresh subagent for tasks that need the same context", because it reuses the prompt cache.

When should you skip a subagent?#

Anthropic's docs suggest staying in the main conversation when the task needs frequent back-and-forth, when planning, building and testing share a lot of context, for a quick targeted change, or when latency matters, since a fresh subagent needs time to gather context. For reusable prompts that should run in the main conversation, a skill fits better.

Common errors and fixes#

Subagents use the session's key, so they hit the same errors as the main conversation:

• INVALID_API_KEY: the key in ~/.claude/settings.json is wrong or was deleted.
• MODEL_PLATFORM_NOT_ALLOWED: the key belongs to a provider other than Claude.
• MODEL_UNAVAILABLE: the model in a subagent's model field isn't available right now. Retry, or set inherit.
• INSUFFICIENT_BALANCE: your balance doesn't cover the request. Top up, then try again.
• API_KEY_QUOTA_EXHAUSTED: the key reached its spend limit, often because several subagents ran at once.

Every code is explained in Errors and fixes.

FAQ#

Do subagents use more tokens?#

Usually yes, in total, since each one builds its own context from scratch. In return, your main conversation stays small, and a short result costs less to carry than the raw output it replaces.

Can a subagent start its own subagents?#

Yes, up to three layers below the main conversation by default. To stop it, leave Agent out of its tools or add it to disallowedTools.

How many subagents can run at once?#

Up to 20 by default. Past that, Claude Code reports Concurrent subagent limit reached. Each one sends its own requests, so parallel runs reach a key's spend limit sooner.

Why doesn't /agents open a setup screen?#

Since version 2.1.198 it points you to the subagent folders instead. Ask Claude to create the subagent, or edit the file in .claude/agents/ or ~/.claude/agents/.

Do subagents work on a 5abeer plan?#

Yes, if your plan includes Claude Code. Subagent requests count toward the plan's limits like the rest of the session. See What each plan runs, the pricing page and Claude API vs Claude Pro/Max.

How do I pay for the API?#

You top up your 5abeer balance with any method in Payment methods, and Claude Code's API calls draw from that balance.

Is 5abeer part of Anthropic?#

No. 5abeer is an independent service, not affiliated with Anthropic.

Sources#

Checked on 2026-11-01:

• Claude Code docs: Create custom subagents
• Claude Code docs: Model configuration
• Claude Code docs: Other LLM gateways

Get started#

Get the 5abeer AI app to run Claude Code and its subagents on your plan, or create a key for Claude models and follow the steps above.