What are subagents and how do you use them in five coding tools?

A subagent works in its own context and hands you the result

When you give a coding agent a big job, it can go two ways: the main conversation does everything itself, or it hands part of the work to a subagent. The subagent does that part in its own context, so the files it reads and the tests it runs do not fill up the main conversation.

Cursor’s documentation says it in two sentences: “Intermediate output stays in the subagent. The parent only sees the final summary.” As of 18 October 2026, five tools have subagents: Claude Code, OpenAI’s Codex, Cursor, Google’s Gemini CLI and GitHub Copilot. Claude Code, Cursor and Copilot talk about the subagent’s own context window; Gemini CLI calls it a separate context loop, and Codex starts agents in parallel and collects their results in one response.

That is why subagents pay off in two kinds of work: jobs with a lot of output (running tests, scanning logs, reading dozens of files) and investigations that do not depend on each other. The examples come from the repository we use every day to build diffox, where we run Claude Code.

A subagent doesn’t see your conversation, so the task must stand on its own

The most common mistake with subagents is to assume they know what was said in the main conversation. According to Claude Code’s documentation, a subagent starts with a fresh context window: it does not see your conversation history, the skills already invoked or the files Claude has read. This is what it starts with:

So the task message has to say, on its own, what the goal is, which files the subagent may touch and what it should report. Whatever you called “that bug” in the main conversation does not exist for the subagent; write down the file path, the error message and the output you expect. Cursor’s documentation says the same: subagents start with a clean context and have no access to earlier conversation history. The Codex, Gemini CLI and Copilot documentation do not say this; whichever tool you use, a task message that stands on its own is the safe choice. Codex’s documentation also recommends asking a subagent to return a summary instead of its intermediate output.

Where each tool keeps subagents, when it delegates, and which come built in

In all five, a subagent is defined in a file that lives at project or user level. Where the tools really differ is whether the main agent hands off work on its own:

Source: each tool’s subagent documentation, 18 October 2026. In Codex a definition is a TOML file; in the others it is a Markdown file with YAML frontmatter. Gemini CLI’s browser agent is off by default. Copilot’s list of built-in agents changes from page to page: the reference page lists seven, the how-to page four.

The tools part ways in the “Delegates on its own?” column. In Codex it depends on the effort level: the models page says the top level, Ultra, runs the work by splitting it across subagents, while the subagents page says local Codex starts a subagent on a direct request such as “spawn two agents”, or on an instruction in AGENTS.md or a skill. In the other four, the main agent can also hand off work on its own; Copilot’s documentation adds that the model may just as well do the work itself instead of delegating it.

Definitions travel between tools: Cursor also reads the .claude/agents/ and .codex/agents/ folders (on a name clash, .cursor/ wins), and Copilot CLI reads .claude/agents/ too. So a file you put under .claude/agents/ is read by Claude Code, Cursor and Copilot CLI; the documentation does not guarantee that the frontmatter fields work the same in all three.

On 18 June 2026, Google stopped serving Gemini CLI to free users and to Google AI Pro and Ultra subscribers and pointed them to Antigravity CLI; with a paid API key or a company licence you can keep using Gemini CLI. We read Antigravity’s subagent documentation on 28 October 2026. Subagents are defined in .agents/agents/ for a project and in ~/.gemini/config/agents/ for the user. The main agent hands a task over by reading the subagent’s description; three agents come built in: research, browser and self. A subagent does not get the main agent’s conversation history and starts with a clean context; if its definition names no model, it runs on the main agent’s model. Subagents can be nested up to 10 levels deep.

A good subagent definition has a narrow job, few tools and a short report

The definition file sets three things: when the subagent is called (the description), what it can reach (the tools) and what it returns (the prompt). In Claude Code it looks like this; the required fields are name and description:

---
name: test-runner
description: Runs the tests and reports only the ones that fail
tools: Read, Grep, Glob, Bash
model: haiku
---

Run the test suite. Report only the failing tests, each with its
error message. Do not edit any file.

• The description is a trigger. Claude Code and Gemini CLI decide whether to delegate by reading the description. Write in it when the agent should be called, not what the agent is.
• Narrow the tools. In Claude Code, the tools field limits which tools the subagent can use; leave it out and the subagent inherits every tool available to subagents. Don’t give a write tool to an agent that only needs to read.
• Permissions come from the main agent. In Codex, a subagent inherits the main agent’s permissions, provider and MCP servers, and a definition file cannot change them. The sandbox and approval settings are the main agent’s too.
• Ask for a short report. Let the last sentence of the prompt say what comes back: the failing tests, the files found, a decision. If long intermediate output is carried back into the main conversation, the point of using a subagent is lost.
• You can turn off automatic use. In the Copilot cloud agent, an agent with disable-model-invocation: true runs only when you select it by hand. In Copilot, a custom agent’s prompt can be at most 30,000 characters.

The model, concurrency and nesting limits differ by tool

If you don’t set a model in the definition, the documentation says a subagent in Claude Code, Codex, Cursor and Copilot runs on the main agent’s model. Gemini CLI’s subagents page says the same, but the model page of the same documentation says the /model command and the --model flag do not change the model subagents use; the two do not quite line up. How many subagents can run at once, and whether a subagent can start another one, depends on the tool:

Source: each tool’s subagent documentation, 18 October 2026. “Not stated in the documentation”: in the pages we read that day, we found no sentence that gives this. Copilot CLI’s reference page gives the depth as 4 in its environment variables section and as 6 in its limits table. By default, Gemini CLI limits each subagent to 30 turns and 10 minutes.

Claude Code looks for the model in four places, in order: the model parameter of that call, the model field in the definition, the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then the main conversation’s model. What happens at the limit is documented too: while 20 subagents are running, a new one cannot start, and the error tells Claude not to retry. Gemini CLI turns nesting off to prevent infinite loops and excessive token use.

In most tools, the effort level doesn’t change how many subagents run

All five tools have a setting for how much thought the model puts into an answer: effort, or reasoning effort. How it relates to subagents comes down to two questions: does a subagent inherit the main agent’s level, and can it pick its own?

Source: each tool’s model and subagent documentation, 18 October 2026. In Cursor, the names of the levels depend on the model.

The Claude Code, Cursor, Gemini CLI and Copilot documentation do not tie effort to the number of subagents. Claude Code’s documentation describes the difference it observed at a higher level: Claude “tested more edge cases and verified more of its work before answering. It also made more choices on its own.” It says nothing about the number of subagents. In Copilot, parallel subagents depend not on effort but on a separate mode: with the /fleet command, the main agent decides for itself whether it can split the work into parts.

The exception is Codex’s top level, ultra. The models page uses the same sentence for the CLI, the app and the IDE: “Ultra mode goes beyond a single-agent run. It uses subagents to accelerate complex work.” In ChatGPT Work, too, Ultra lets ChatGPT hand suitable work to subagents on its own. At the other levels, according to the subagents page, local Codex starts a subagent when you ask, or when AGENTS.md or a skill tells it to.

Claude Code’s ultracode setting splits the work across dozens of subagents

Next to the effort levels, Claude Code’s /effort slider has an ultracode toggle. The documentation describes it not as a level but as a separate setting: “a Claude Code setting rather than a model effort level”. With it on, Claude plans a dynamic workflow for every substantive task without being asked: it writes a script that splits the work and manages the subagents, and a runtime executes the script in the background while your session stays responsive.

There are four ways to turn it on:

• For one task: put the word ultracode in your prompt; the session’s effort level does not change. The word only counts in a prompt you type yourself.
• For the session: /effort ultracode, or the toggle on the slider.
• At launch: claude --effort ultracode, which also sets the effort level to xhigh.
• In every session: "ultracode": true in the settings file.

The documentation is clear about the cost: every request uses more tokens and takes longer, and on a subscription you reach your session or weekly limit sooner. With ultracode on, the limit of 20 subagents is not enforced; a workflow has limits of its own: by default 16 agents at once and at most 1,000 agents in a run. With ultracode off, more than 25 agents, or a projected total above 1.5 million tokens, brings up a “Large workflow” warning; with ultracode on, that warning is not shown either.

Dynamic workflows arrived at the end of May 2026 and were announced as a “research preview” in the weekly digest; on 18 October 2026 the workflows page carried no status label. Don’t confuse ultracode with two things that have similar names: ultrathink asks for deeper thinking on that turn only and does not change the effort level; /code-review ultra is a separate command that runs review agents in the cloud, and Claude does not start it on its own.

Can subagents talk to each other?

In all five, a subagent’s result goes back to whoever called it. The tools differ on three questions: can subagents write to each other, can the main agent write to a running or finished subagent later, and is there a team feature?

Source: each tool’s documentation, 18 October 2026. In Copilot, writing to sibling agents needs shared sibling communication to be on; the documentation does not say how to turn it on.

Claude Code’s agent teams take this furthest: one session is the team lead, the members are separate sessions, each works in its own context window, and they write to each other by name. There is no broadcast; each recipient gets a separate message. The documentation’s own rule of thumb: “Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.” Agent teams are experimental and off by default, and they use more tokens because each member is a separate Claude instance.

Being able to message each other does not mean you should depend on it. The sturdiest setup is still to split the work into independent parts and combine the results in the main agent. Copilot’s fleet documentation says the same: coordination runs on explicit state, not implicit shared memory, and subagents keep no state between calls, so give each one complete context.

Parallel agents need separate worktrees and separate files

Subagents that only read can work side by side in the same directory. The trouble starts when several agents edit files and commit: they share the same directory, the same branch and the same git index. That is a git problem, whichever tool you use. Our repository has four rules for it.

A separate worktree. In Claude Code, if you add isolation: worktree to the definition, the subagent gets a temporary worktree, a separate working directory of the repository, which is removed automatically if the subagent finishes without changes. According to the documentation, this worktree branches by default from the repository’s default branch, not from the branch you are working on.

Separate files. Our rule for agents that share one directory: each commits only its own paths (git commit --only <paths>), because a bare git commit takes the whole index, including work another agent has staged. When you split the work, give each agent its own set of files.

A task message that stands on its own. In Claude Code and Cursor a subagent does not see your conversation history; the task message has to say, on its own, what the goal is, which files it may touch and what it should report. Hooks in the settings file, on the other hand, reach it automatically: in Claude Code a PreToolUse hook also runs before a subagent’s tool calls.

Cleanup. A worktree with changes stays on disk. On 27 August 2026, 41 worktrees had piled up in our repository, 37 of them from a single review round. The clutter came from workflows, not people, so that is where the fix went: every session opens with a script that removes the branches of merged pull requests and the worktrees whose work is done.

Not every task needs a subagent

A subagent protects your context, but it builds its own from scratch; writing the task message and reading the result cost something too. Claude Code’s documentation recommends staying in the main conversation when:

• The task needs frequent back-and-forth. You will refine the work together, step by step.
• The phases share the same context. Planning, implementation and testing rest on the same information.
• The change is small and targeted. A few lines in one file.
• Speed matters. A subagent starts from scratch, and gathering context takes time.

A subagent fits work that answers one question on its own: “run the tests and bring back the failures”, “who calls this module?”, “compare these three libraries”. diffox’s review rests on the same idea: it splits an AI code review across specialist agents, and each one looks at the change with its own question. We explain how they are chosen in our architecture post.