Subagents for coding agents

A subagent is a specialised assistant your coding agent can hand a job to. In Claude Code it is one Markdown file with a name, a description of when to use it, an optional tool list and a system prompt. The subagent works in its own context window and returns a summary, so your main conversation stays clean. Codex, Gemini CLI and Cursor have their own versions. We checked each docs page on 31 October 2026.

Quick facts

What a subagent does for you

Think of a subagent as a colleague you give one clear brief. It reads files, runs searches or checks, and comes back with a short report. The long output stays in its own window.

Claude Code's docs list three good reasons to use one:

• The task produces verbose output you do not need in your main context, such as test logs or a wide codebase search.
• You want to enforce specific tool restrictions or permissions, such as a reviewer that cannot edit files.
• The work is self-contained and can return a summary.

The same page lists when to stay in the main conversation: tasks that need back and forth, phases that share a lot of context (plan, build, test), quick targeted changes, and cases where latency matters, since a fresh subagent has to gather context first.

Built-in subagents in Claude Code

You get some without writing anything:

Explore and Plan start without your CLAUDE.md and the git status snapshot, to keep research quick and cheap. A subagent you define with the name Explore overrides the built-in, so you can set model: haiku on it to run exploration on a cheaper model.

Write a subagent

The shortest path is to ask Claude to write it. The docs show this prompt:

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

The result is a file like this:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Then call it: "Use the code-improver agent to suggest improvements in this project." Claude shows the delegation as a tool row such as code-improver(Suggest code improvements).

One gotcha from the docs: if ~/.claude/agents/ did not exist before the session started, a running session does not detect the new directory. Restart Claude Code.

The frontmatter you will use

Field names use camelCase and must match exactly. Claude Code ignores a field it does not recognise, with no error. To catch a typo, run claude --debug and search the log for does not recognize or apply.

Files are skipped without a message in the session when they have no name, no description, a name that starts with - or contains :, an opening --- that is not the first line, or YAML that does not parse. The reason goes to the debug log. You can also run claude plugin validate against an agents directory.

Where to save it

If two share a name, the higher priority wins. Commit project subagents so the team shares and improves them. Claude Code scans these folders recursively, so subfolders such as agents/review/ are fine.

Other agents

Codex

Standalone TOML files in ~/.codex/agents/ or .codex/agents/. Each must define name, description and developer_instructions. Codex's docs show:

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model_reasoning_effort = "high"
developer_instructions = """
Stay in exploration mode.
Do not edit files.
Trace the real execution path, cite files and symbols.
"""

Custom agents inherit the parent's permissions, provider and MCP servers; the file cannot override them. Codex ships built-ins named default, worker and explorer. Global settings sit under [agents] in config.toml; the docs show max_concurrent_threads_per_session = 8 as an example.

Gemini CLI

Markdown with YAML frontmatter in .gemini/agents/ (shared) or ~/.gemini/agents/ (personal). The docs show an example with kind: local. You can force one with the @ syntax, for example @codebase_investigator Map out the relationship between the AgentRegistry and the LocalAgentExecutor. The docs also list a built-in @generalist.

Cursor

Create .cursor/agents/verifier.md with name and description frontmatter and the prompt as the body. Cursor's docs also list .claude/agents/ and .codex/agents/ as places it reads, project and user level. Its example uses readonly: true and model: inherit.

Compatibility at a glance

A Claude Code subagent file can often work in Cursor unchanged because Cursor reads the same folder. Codex needs a rewrite as TOML.

Where to find subagents

On 31 October 2026 the VoltAgent repo showed about 26,000 stars, and wshobson/agents about 42,000. Stars tell you what is popular, not what is good. Read the prompt before you install.

Example: a read-only code reviewer

This one comes straight from Claude Code's docs. Note the tool list: no Edit, no Write.

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

The docs also include a debugger, a data scientist and a database query validator as examples.

How to write a good one

1. Narrow job. "Review diffs for security" beats "be a good engineer".
2. Description as trigger. Say when to delegate and use phrases like "use immediately after writing code" if you want Claude to do it unprompted.
3. Least tools. If it only reads, give it only read tools. This is also your safety net.
4. Say what to return. A short, prioritised report. The parent only sees the summary.
5. Pick the model on purpose. haiku for search-heavy work, inherit or opus for judgement. Claude Code's docs also describe an environment variable, CLAUDE_CODE_SUBAGENT_MODEL, that sets a model for every subagent.
6. Preload skills with the skills field when it always needs the same procedure. The full skill content is injected. See agent skills.

Two more subagents worth having

The code reviewer from the docs is the standard first one. These two cover jobs that generate long output, which is the clearest reason to use a subagent at all. They are our sketches that follow the same frontmatter fields, so adjust the wording to your project.

A test runner that returns only what matters

---
name: test-runner
description: Runs the project's tests and reports failures concisely. Use after code changes, or when the user asks whether tests pass.
tools: Read, Grep, Glob, Bash
model: haiku
---

Run the project's test command. Do not edit any file.

If everything passes, reply with one line: the number of tests and the time.
If tests fail, list each failing test with its name, the assertion message
and the file and line of the failure. Include no passing output and no
stack frames beyond the first two. End with the single most likely cause.

A codebase explorer that answers a question, not dumps files

---
name: area-explorer
description: Finds where something is implemented and explains how it works. Use before changing unfamiliar code.
tools: Read, Grep, Glob
model: haiku
---

You answer one question about how this codebase works.

Search, read what you need, then reply in under 200 words: the files that
matter (with paths), the call flow in plain words, and anything surprising.
Quote no more than five lines of code. Do not suggest changes.

Both use haiku because the work is search and summary, where a small model is usually enough, and both restrict tools. The test runner has Bash because it must run the command, and the explorer has none, since it only reads. Neither can edit files, so neither can make a mess. The point of both is the return format: the parent receives a short report and the long output stays in the subagent's window.

How to brief a subagent

A subagent starts without your conversation, so the prompt you send it carries everything. Claude decides when to delegate from the description, and you can also ask directly. A good delegation names the question, the scope and the shape of the answer.

State what you already know, because the subagent does not. "We already ruled out the cache layer" saves it from repeating that work. State the stopping point too: "stop after you have the three most likely causes". Without one, a subagent can keep searching and spend tokens on completeness you did not need.

Does the subagent earn its place?

A subagent is worth keeping if the parent does better with it than without. A short check tells you:

1. Run the task twice, once in the main conversation and once through the subagent, on the same change.
2. Compare the reports, not the length. Which one found the real issue, and which one buried it?
3. Compare the main context afterwards. Run /context in each. The point of a subagent is a smaller, cleaner main window.
4. Compare the cost. Each subagent has its own context and model calls, so the total can be higher even when the main window is cleaner.
5. Watch for missed context. If the subagent keeps lacking something you told the parent, put that fact in its prompt or in CLAUDE.md.

If a subagent does not win on at least one of quality, context or speed, delete it. A short list of subagents you use beats a folder of forty you do not.

What parallel subagents cost

The docs warn that running several subagents multiplies token use, since each one has its own context. A worked example shows the effect. Take a task where one agent would read 60,000 input tokens and write 3,000 output tokens, and suppose you split it across four subagents that each read 40,000 input tokens and write 1,500 output tokens. These sums use example token counts, with Sonnet 5.5 at $2 and $10 per million.

Parallelism buys time and a clean main window, at about two and a half times the cost on the same model. Using a smaller model for the search-heavy workers brings the bill far below the single-agent baseline, and that is the usual reason to set model: haiku on exploration subagents. Keep the judgement and the final edit on a stronger model in the main conversation.

Safety and cost

• Permissions are inherited. Built-in subagents inherit the parent's permission rules. Setting permissionMode: bypassPermissions on a custom one is a deliberate act; do not copy it from a random repo.
• Tool lists are the guard. A subagent with no tools field gets every tool. Be explicit.
• Third-party files are code. A subagent prompt can tell the agent to run commands. Read before installing, especially from large lists.
• Tokens add up. Each subagent has its own context and its own model calls. Several in parallel multiply cost. By default, when 20 subagents are running in a session, spawning another fails with Concurrent subagent limit reached.
• Block what you do not want. Add a built-in type to permissions.deny, or deny the Agent tool to stop delegation entirely. CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 removes Explore and Plan.

Limits and known issues

• Fresh context. A subagent starts without the conversation, unless you use a fork. It can miss things you already told the parent.
• Silent frontmatter errors. Misspelled fields are ignored. Use the debug log.
• Subagents that spawn subagents need to be allowed explicitly; the docs have a section on it.
• Directory timing. A new agents directory is not noticed until restart.
• Format drift across tools. Claude Code is Markdown with camelCase fields, Codex is TOML, Gemini adds kind. A file is not automatically portable.
• Version-dependent features. Some Claude Code fields, such as maxTurns partial output and autoCompactWindow, need recent versions per the docs.

Subagents compared with the other add-on types

For a full working example of how these pieces combine, see Claude Code workflows and the Claude Code agents guide.

Our take

We did not build or benchmark these subagents for this page. This is an editorial reading of four docs sets and two public repos.

The strongest use is the read-only specialist: a reviewer, an explorer, a log reader. It is cheap to write, safe by construction, and it keeps your main window clear. The weakest use is the "senior engineer" persona with every tool. That is a general agent in a costume, and it adds a hop.

Do not install a hundred subagents because a list has a hundred. Descriptions load into context, and Claude has to choose between them. Pick three that match your week, write one for your own repo's rules, and delete what you do not use.

Because Cursor reads Claude and Codex folders, a team on mixed tools can keep a single set of Markdown agents and test it in both. That is worth trying before you maintain three formats.

Frequently asked questions

What is a Claude Code subagent? A Markdown file that defines a specialised assistant with its own prompt, tools and context window.

Where do subagent files go? .claude/agents/ or ~/.claude/agents/, or inside a plugin.

Which fields are required? Only name and description.

Do other agents have subagents? Yes. Codex uses TOML, Gemini CLI and Cursor use Markdown.

When should I not use a subagent? For quick edits and work that needs lots of back and forth.

*Product names are used descriptively. We are not affiliated with Anthropic, OpenAI, Google or Cursor.*