Helpers & subagents
What it is
While a session works, it can bring in others to work with it. There are two kinds:
- Helper: another session that a session brings in to work on the same job. It has its own copy of the code, can use another agent or model, and you can open it to look or chime in.
- Subagent: a copy of the session that it sends out itself. It uses the same code and the same agent to look something up, read a few files, or run a check, and hands back the result when done, within tens of seconds to a few minutes.
Click the "Helpers N · Subagents N · Background N" chip under the session's input box to see them. ("Background" is commands the session runs in the background, like a local preview or tests.)
Telling them apart in one table:
| Helper | Subagent | |
|---|---|---|
| Code | Its own copy, merged back when done | Works in the session's own copy |
| Which agent | Can switch agent and model | Same agent as the session only |
| A separate session? | Yes; you can open it to look and chime in | No; you can only see it inside the session |
When to use it
Usually the session decides for itself: work that takes a while, changes code and can run in parallel goes to a helper; looking something up or reading a few files goes to a subagent.
You can also just say:
- "Get a helper to write the tests while you carry on with the API." (Splitting up the work)
- "Get a Codex helper to review these changes." (A second check from another agent)
- "The signing certificate is only on the Mac Studio, so get a helper on that one to package it." (Across computers)
When you say "use Codex as a subagent", it opens a Codex helper instead, because an agent's own subagents can only be the same agent.
How to use it
Four ways to use helpers
- Splitting up the work: for work that takes time and can run in parallel, like writing a set of tests or building another API. Each helper has its own copy of the code, and the session that brought it in merges it back when done.
- A second check from another agent: Claude Code writes the code, and a Codex helper writes tests or reviews it, or the other way round. If not specified, a helper uses the same agent, model and thinking effort as the session that brought it in. A helper can also be told which model preset to use.
- Read-only review: see "Review helpers" below.
- Across computers: when the work needs a key, a device or a tool that only another computer has, the session can bring in a helper right on that computer. The helper works in that computer's copy of the project, pushes a branch back when done, and the session pulls it down and merges it. Keys are never copied between computers.
Who manages helpers
- A helper only answers to the session that brought it in: it goes to that session with anything, not to you; if something goes wrong, that session deals with it.
- Things a helper needs approved show up in the session that brought it in, and you approve them there; no need to open the helper. (When that session is set to "Allow everything", the helper doesn't ask either.)
- To see what it's doing, just open it; to chime in, type in the input box at the bottom of the helper's page.
- Helpers are listed in the left sidebar under the session that brought them in, with the model in grey text, for example "2 helpers running".
- When a helper finishes, it automatically hands back its last reply, its changes and its branch, and wakes the session that brought it in.
- Helpers follow the session that brought them in: when that session stops, is done, or is marked "Won't do", its helpers stop too. Interrupting a turn of that session doesn't stop the helpers.
Helpers can't bring in helpers of their own (but they can send out their own subagents), and they can't create tasks, hand in tasks, push, or deploy. A helper's permissions always follow the session that brought it in, never wider.
Review helpers
When a session has changed something where a mistake is costly, like protocol, permissions, data or money, it brings in a read-only helper to review the changes before handing them in.
- Look only: it's locked read-only when it starts, so it can't change files or run commands. This is enforced, not just asked for. The helper's card says "Read-only review".
- Another agent reviews by default: if the session uses Claude Code, it brings in Codex, and the other way round. If the other agent isn't installed, isn't signed in, or has used 90% of its quota, the same agent is used. To pick a specific one, write "review" in a model preset's "When to use".
- When done, it hands its findings back to the session that brought it in, and the session makes the fixes itself.
- The same version of the changes is reviewed only once, and a task gets at most 3 reviews, so it never goes on forever.
A session switching agents for a helper asks you first
When a session wants to open a helper with a different agent or model from its own, and you didn't ask for it yourself, it asks you first in "Needs you": who wants it, which agent and model, why it's switching, and what the helper will do.
- It only opens once you click "Agree"; if you click "Don't switch", it uses the same as itself;
- Click "Stop asking", and this project won't ask again; you can revoke it in "Things you don't need to ask me";
- It spends the quota of your own subscription with that agent, and it's still held back at 90%;
- The row in the left sidebar says "Switched: Codex"; open it to see why.
When opening a helper, the session can see how much of this computer's Claude and Codex quota has been used, and is reminded not to pick the one that's nearly full.
Review helpers don't ask, because they're read-only.
Subagents
- Mostly they look things up, read code and run checks; several can run at once, and they can change files too.
- Several changing the same code at once tend to step on each other.
- You can only watch, not chime in. They don't come to you on their own, and they don't appear in the left sidebar.
FAQ
Is there a limit on how many helpers? There's no set limit, and no limit on which models they use. But 3 or more helpers changing code are hard to merge back, so the session is reminded to ask Q to split the work into several tasks first. The safety nets are three things: usage at the bottom left, stopping automatically when quota runs out, and helpers not being able to bring in helpers.
Do helpers count toward a computer's "how many run at once" limit? No.
Can I see how much a helper spent? Yes. The usage page can show Q, working sessions and helpers separately. See Usage & quota.
What about tasks with "Show me the plan first" on? Only once you approve the plan does the session start changing code and bringing in helpers as planned.