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

> How Claude Code subagents work, how to write one in .claude/agents, which model each one runs on, and what they cost on an API key.

Updated: 2026-11-01

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:

```text
---
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:

| Model | Id | Input (ours) | Output (ours) | Context |
| --- | --- | --- | --- | --- |
| Claude Sonnet 5.5 | `claude-sonnet-5.5` | $0.60 | $3 | 1M |
| Claude Opus 5.5 | `claude-opus-5.5` | $1.20 | $6 | 1M |
| Claude Fable 5.1 | `claude-fable-5.1` | $3 | $15 | — |

Every model that runs in Claude Code is on the [Claude Code setup page](https://5abeer.ai/en/docs/apps/claude-code.md#models).

## 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. Top up your balance

Pay with one of the [payment methods](https://5abeer.ai/en/docs/start/payment.md). Every subagent request is deducted from this balance.

### 2. Create a key for Claude models

Create a key for the Anthropic provider, as in [Create a key](https://5abeer.ai/en/docs/start/keys.md#create). Name it `claude-code` so its usage is easy to find.

### 3. Add the settings

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

`~/.claude/settings.json`

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

### 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](https://5abeer.ai/en/docs/apps/claude-code.md#easy), 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:

Example: 400,000 input tokens and 20,000 output tokens on Claude Sonnet 5.5 (`claude-sonnet-5.5`) cost $0.30 at our price against $1.00 at the official price (70% lower). Official price checked October 19, 2026.

The same job on the newest Opus, [`claude-opus-5.5`](https://5abeer.ai/en/models/claude-opus-5.5):

Example: 400,000 input tokens and 20,000 output tokens on Claude Opus 5.5 (`claude-opus-5.5`) cost $0.60 at our price against $2.00 at the official price (70% lower). Official price checked October 19, 2026.

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](https://5abeer.ai/en/docs/start/keys.md#controls), and check it in [Track your usage](https://5abeer.ai/en/docs/start/pricing.md#usage). Our price next to the official one is on the [Claude API page](https://5abeer.ai/en/api/claude), and [The cheapest way to use Claude Code](https://5abeer.ai/en/guides/claude-code-cheapest-way) 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`](https://5abeer.ai/en/docs/help/errors.md#INVALID_API_KEY): the key in `~/.claude/settings.json` is wrong or was deleted.
- [`MODEL_PLATFORM_NOT_ALLOWED`](https://5abeer.ai/en/docs/help/errors.md#MODEL_PLATFORM_NOT_ALLOWED): the key belongs to a provider other than Claude.
- [`MODEL_UNAVAILABLE`](https://5abeer.ai/en/docs/help/errors.md#MODEL_UNAVAILABLE): the model in a subagent's `model` field isn't available right now. Retry, or set `inherit`.
- [`INSUFFICIENT_BALANCE`](https://5abeer.ai/en/docs/help/errors.md#INSUFFICIENT_BALANCE): your balance doesn't cover the request. Top up, then try again.
- [`API_KEY_QUOTA_EXHAUSTED`](https://5abeer.ai/en/docs/help/errors.md#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](https://5abeer.ai/en/docs/help/errors.md).

## 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](https://5abeer.ai/en/docs/subscriptions/plan-apps.md#claude-code), the [pricing page](https://5abeer.ai/en/pricing) and [Claude API vs Claude Pro/Max](https://5abeer.ai/en/guides/claude-api-vs-subscription).

### How do I pay for the API?

You top up your 5abeer balance with any method in [Payment methods](https://5abeer.ai/en/docs/start/payment.md#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](https://code.claude.com/docs/en/sub-agents)
- Claude Code docs: [Model configuration](https://code.claude.com/docs/en/model-config)
- Claude Code docs: [Other LLM gateways](https://code.claude.com/docs/en/llm-gateway)

## 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.