What are subagents? Claude Code, Codex, Cursor and Grok Build

A subagent is a separate agent that your coding agent starts to handle one task. It works in its own context window, with its own instructions, and sends back a short summary when it’s done.

How subagents work

Say you ask your agent to find every place the app calls the payments API and check the error handling. Reading all those files fills the conversation with code you’ll never look at again, and that leaves less room for the work that follows.

With a subagent, the main agent writes a brief and hands the task off. The subagent reads, searches and runs commands in a fresh context. When it finishes, only its summary comes back to the main conversation.

A fresh context cuts both ways. The subagent doesn’t see your conversation, so it can’t be confused by a long session. It also doesn’t know anything you didn’t put in the brief.

Claude Code, Codex and Cursor document a file format for your own subagents. Each one has a name, a description of when to use it, and instructions. Most also let you pick the model and limit what the subagent can do.

Subagents in each tool

All four tools ship built-in subagents and let you add your own. They differ in file format, in when the main agent decides to delegate, and in how much you can restrict a subagent.

Claude Code

Claude Code reads subagents from .claude/agents/ in your project and ~/.claude/agents/ for every project. A subagent is a Markdown file with YAML frontmatter, and only name and description are required. The body becomes the subagent’s system prompt.

Optional fields include tools to limit what it can use, model (sonnet, opus, haiku, fable, a full model ID, or inherit), skills to preload skills, and isolation: worktree to give it its own Git worktree.

Claude decides when to delegate by reading the description. The docs suggest adding phrases like “use proactively” when you want it to delegate without being asked. You can also name a subagent in your prompt, @-mention it with @"code-reviewer (agent)", or run a whole session as one subagent with claude --agent code-reviewer.

A subagent Claude starts from the main conversation runs in the background by default. It doesn’t see your conversation history or the files Claude already read. If you want a helper that does, Claude Code also has forks, which you start with /subtask followed by a task.

The built-in Explore subagent is read-only and made for searching a codebase. Plan gathers context during plan mode. Read more in the Claude Code subagents docs.

OpenAI Codex

Codex reads custom agents from .codex/agents/ in the project or ~/.codex/agents/ for all projects. Each file is TOML and must define name, description and developer_instructions. You can also set model and model_reasoning_effort.

The built-in agents are default, worker for implementation, and explorer for read-heavy exploration.

Local Codex starts subagents when you ask for them directly, or when a project or skill instruction tells it to. When several are running, Codex waits for all of them and returns one consolidated answer. In the CLI, /subagents switches between the agent threads.

Subagents inherit the parent’s permissions, provider and MCP servers, and a custom agent file can’t change them. See the Codex subagents docs.

Cursor

Cursor reads subagents from .cursor/agents/ and ~/.cursor/agents/. For compatibility it also looks in .claude/agents/ and .codex/agents/, at both project and user level. When two folders define the same name, the .cursor/ one wins.

A subagent is a Markdown file with YAML frontmatter. The fields are name, description, model (defaults to inherit), readonly and is_background. Setting readonly: true blocks file edits and state-changing shell commands.

Cursor ships two built-in subagents: Explore for codebase searches and Browser for browser automation. You can call a subagent by name with a slash, like /verifier confirm the auth flow is complete.

A foreground subagent blocks until it finishes. A background one returns immediately. When the agent starts several in one message, they run at the same time. See the Cursor subagents docs.

Grok Build

In Grok Build, subagents are child sessions with their own context that return a summary to the parent. They’re on by default, and --no-subagents turns them off for a session.

The built-in types are general-purpose, explore (read, list and search only, no shell or edits) and plan (drafts a plan, no shell or edits). You add or override types under .grok/agents/ or ~/.grok/agents/, and manage them with /config-agents.

Grok also has personas, which change a subagent’s tone and focus without changing what it can do. See the Grok Build subagents docs. My Grok Build tutorial has a section on delegating work to subagents.

Details checked against each vendor’s documentation in October 2026.

A real example

Here’s a read-only subagent that checks internal links in a Markdown blog. This site keeps its posts in src/posts/, so we’ll use that layout.

In Claude Code, save it as .claude/agents/link-checker.md:

---
name: link-checker
description: Checks internal links in Markdown posts. Use proactively after a post is edited.
tools: Read, Grep, Glob
model: haiku
---

You check internal links in Markdown files under src/posts/.
For every link that starts with /, confirm a matching file exists in src/posts/ or src/pages/.
Reply with a short list of broken links, with the file and line for each one.
Do not suggest other changes.

The tools line keeps it read-only. The haiku model is enough for this job.

Then ask for it by name:

Use the link-checker agent to check src/posts/agents-md.md

Cursor finds the same file, because it also reads .claude/agents/. Cursor doesn’t document a tools field, though. To make the agent read-only there, put a copy in .cursor/agents/ with readonly: true.

In Codex, the same agent is a TOML file in .codex/agents/link-checker.toml:

name = "link_checker"
description = "Checks internal links in Markdown posts after a post is edited."
developer_instructions = """
Check internal links in Markdown files under src/posts/.
For every link that starts with /, confirm a matching file exists in src/posts/ or src/pages/.
Reply with a short list of broken links, with the file and line for each one.
Do not edit files.
"""

Notice the last line. In Codex, “Do not edit files” is an instruction, not a permission. The subagent runs with the parent’s sandbox and approval settings.

When to use a subagent

Use one when a task reads a lot and returns a little. Exploring an unfamiliar codebase, finding every usage of a function, or reading a long log are good fits. The reading stays in the subagent’s context, and you get the conclusion.

Use one for a second look. In Claude Code and Cursor a subagent starts with a clean context, so a reviewer judges the change from the brief and the code, not from the reasoning that produced it.

Use several when the tasks don’t touch the same files, like researching three libraries before you pick one.

Skip it for small tasks. The Claude Code docs warn that a fresh subagent has to gather context your conversation already had, so it can end up slower. Cursor’s docs say the same: the benefit is context isolation, not speed.

Pitfalls

Token use adds up, because every subagent sends its own requests. Cursor’s docs estimate that five parallel subagents use roughly five times the tokens of a single agent. In Claude Code, subagent requests count toward the same usage limits as your main conversation.

Two subagents editing files at once can overwrite each other’s changes. Give each one separate files, or separate worktrees. Claude Code’s isolation: worktree sets that up for you, and my post on Git worktrees explains how they work.

The brief is all a subagent knows. If a decision from your conversation matters, write it in the prompt or in a file the subagent reads.

Be careful with instructions that sound like limits. In Codex, a custom agent inherits the parent’s sandbox and approvals whatever its instructions say. In Grok Build, subagents inherit the permission mode and aren’t held back by the parent’s plan mode. Check the permission mode before you delegate.

Cursor’s docs also advise against creating dozens of generic subagents. With vague descriptions the agent won’t know when to use them, so a few specific ones work better.

Related on flaviocopes.com

• Parallel coding agents: how to coordinate and review changes covers splitting work so parallel agents don’t step on each other.
• Use AI to understand code shows the kind of research a read-only subagent is good at.
• Skill Cabinet is my Mac app for the skills your coding agents load. It’s useful when you preload skills into Claude Code subagents with the skills field, because it shows which agents can see each skill.

Related glossary entries

• Context window: The context window is everything a coding agent can see at once. How to check it, free it and keep it small in Claude Code, Codex, Cursor and Grok Build.
• Plan mode: Plan mode makes a coding agent research and propose a plan before it edits code. How it works in Claude Code, Codex, Cursor and Grok Build, and when to use it.
• Permission modes: Permission modes decide what a coding agent can do without asking. The modes in Claude Code, Codex, Cursor and Grok Build, and what YOLO mode really skips.
• Hooks: Hooks run your own scripts when a coding agent calls a tool or stops. How hooks work in Claude Code, Codex, Cursor and Grok Build, with examples.

All AI glossary entries →

Want me to talk about your product? You can sponsor this site.