How to Run Codex and Claude Code Subagents in Parallel: Prompts, Settings and Commands Compared

The common impression that "Claude Code goes parallel on its own, but Codex won't unless you tell it to" is true, with conditions. The Codex app, CLI and IDE extension spin up parallel workers (subagents) when you ask, or when AGENTS.md or a skill tells it to split work into subagents. Claude Code also delegates on its own judgment, based on the content of your request and each subagent's description.

This article compares how to get parallel work out of the two tools, based on the official OpenAI and Anthropic documentation (checked October 26, 2026), in this order: triggers, how to write instructions, configuration, commands and cost. In every section the two tools appear in the same order and colors: Codex → Claude Code. At the end, I summarize lessons this site learned from running subagents in parallel with Claude Code.

1. What triggers parallel work, and what happens if you say nothing

A subagent is a separate worker that takes over part of the job from the main conversation. Each one runs research or tests in its own context and returns only a summary of its results to the main conversation. Running them in parallel cuts waiting time and keeps the main conversation from filling up with intermediate logs. Both tools share this idea.

What differs is who starts it. Here are four situations.

Sources: OpenAI "Subagents"; Anthropic "Create custom subagents". Checked October 26, 2026.

According to the official Codex documentation, the local versions of Codex (app, CLI, IDE extension) delegate "when directly asked, or when relevant AGENTS.md or skill instructions call for delegation." The feature isn't switched off: the subagent system is enabled by default in current versions. Whether to spawn is left to your instructions. In ChatGPT Work (web), most intelligence levels require an explicit request, and only when you choose Ultra (Ultra is limited to eligible accounts and supported models) can it delegate on its own when going parallel would substantially improve speed or quality.

The official Claude Code description is that it "delegates automatically based on the task in your request, the description in the subagent definition, and the current context." For subagents you want used more proactively, it recommends putting phrases like "use proactively" in the description. Subagents that inherit the conversation as-is (forks) are also spawned by Claude at its own discretion by default.

A fine point: the Codex changelog includes a change that lets those embedding Codex in their own products (app-server clients) choose delegation from "disabled, explicit requests only, or proactive" (Codex CLI 0.142.0, June 22, 2026). For users of the app, CLI and IDE, the behavior is as in the table above.

2. How the two work, side by side

Here is how subagent definitions are written, how many can run at once, how working directories are separated, and more. Where only one side's official docs cover something, it is marked "Not documented."

Sources: OpenAI "Subagents", "Configuration Reference", "Worktrees"; Anthropic "Create custom subagents", "Run parallel sessions with worktrees". Checked October 26, 2026.

There are two big differences. The first is whether you can make a subagent unable to write. Codex uses the parent's permissions as-is, so telling a subagent "don't edit" is only a request. Claude Code can strip the editing tools (Write, Edit) from a subagent entirely. To block writes from the shell too, remove Bash as well. The second is a working copy per subagent: Claude Code can create a git worktree (a separate working copy of the same repository) for each subagent, while Codex worktrees are per chat.

Claude Code has other ways to run in parallel besides subagents (agent view, which runs separate sessions on one screen, and agent teams, where workers communicate with each other). The differences are covered in "Claude Code Subagents vs Agent Teams" and "Claude Code's agent view".

3. How to write instructions, with ready-to-use prompts

The official Codex docs recommend that a good prompt states how to split the work, whether to wait for all agents before continuing, and what to return. From running subagents in parallel on this site, adding two more items cuts down on accidents.

1. How to split the workBy concern (security, tests, maintainability), by location (directory, module), and so on. Split so that no two subagents look at the same thing
2. What they may touch"Read only," or "you may edit only this directory." Never let two subagents touch the same file
3. Whether to wait for allCombine only once every result is in, or allow moving on midway
4. What to returnFormat and length ("under 10 lines with file names," etc.). Long replies fill the main context quickly
5. What not to doCommitting, pushing, subagents spawning more subagents, and so on. If they aren't told what's off limits, subagents will do it with good intentions

Read-only research and reviews (start here)

Review this branch against main. Spawn three subagents in parallel:
one for security issues, one for missing tests, and one for maintainability.
None of them should edit any files.
Wait until all three are done, then summarize by concern, with file names and line locations.

Research the authentication, database, and API modules in parallel using separate subagents.
Every subagent should only read, not change any files.
Have each return "entry-point files, main processing flow, concerns" in under 10 lines,
and combine them into one only after all results are in.

Splitting up work that edits files

Both sets of official docs treat parallel, write-heavy work with caution. Give each subagent its own area it may edit, and in Claude Code, separate the working copies too.

Find out why saving on the settings page fails, and fix it.
Have browser_debugger reproduce it in the browser and record the steps,
and have code_mapper find where the responsible code is (these two must not edit anything).
Once the cause is known, have ui_fixer make the smallest fix. Don't touch unrelated files.

/batch migrate the JavaScript in src/ to TypeScript

Not having to say it every time

If having to ask for parallel work every time in Codex is a hassle, write delegation rules in the project's AGENTS.md. The official docs say it delegates when relevant AGENTS.md or skill instructions exist. They don't say which wording reliably triggers it, so after you write the rules, check once whether subagents start for your usual requests.

## Using subagents
- For research spanning three or more directories, spawn one subagent per directory and research in parallel
- Don't let subagents edit files. Do all editing in the main thread
- Wait until all results are in, then report only the key points

In Claude Code, if you want a particular subagent used more, write in its description when to use it, plus "use proactively" (see the next section for a definition example). Conversely, if it delegates too much, adding Agent to permissions.deny stops it from spawning subagents.

4. Configuration and subagent definition files

Codex config.toml and .codex/agents/

Global settings go under [agents] in config.toml (personal: ~/.codex/config.toml, project: .codex/config.toml).

# .codex/config.toml
[agents]
max_concurrent_threads_per_session = 4     # Max subagent threads open at once (main thread not counted)
default_subagent_model = "gpt-6-luna"      # Default model for subagents
default_subagent_reasoning_effort = "high" # Default reasoning effort for subagents

Source: OpenAI "Configuration Reference". Checked October 26, 2026. The "multi agent v2" you often see in search results is the current version of this system; per the changelog, it became stable in Codex CLI 0.145.0 (July 21, 2026) (Changelog). In current versions it is enabled without writing multi_agent = true yourself.

Custom agents go in .codex/agents/, one TOML file per agent. The agent's name comes from name, not the file name.

# .codex/agents/reviewer.toml
name = "reviewer"
description = "Reviewer focused on correctness, security, and missing tests"
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
Do not edit files.
Prioritize correctness, security, behavior regressions, and missing tests.
Raise style-only comments only when they hide a real bug.
"""

Adapted from the official example. The model names are from the official example; available models vary by account and workspace. The official guidance is gpt-6.1-sol for agents making heavy judgment calls and gpt-6-luna for lightweight agents with a clearly bounded scope. Settings such as sandbox_mode, approval_policy and mcp_servers are overridden by the parent's settings even if you write them in the agent file.

Claude Code .claude/agents/ and settings.json

Subagents live in .claude/agents/ as Markdown. You can also just ask Claude to "create a subagent that does X" and have it write the file.

---
name: test-runner
description: Runs the test suite and reports only failing tests with their errors. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: haiku
---

Run the tests and return only the names of failing tests and the gist of their errors.
Do not fix code. Do not return the list of passing tests.

Because tools doesn't include Write or Edit, per the official docs this subagent can neither edit nor write files. However, Bash is kept so it can run the tests, which leaves room for writing through shell commands. "Do not fix code" in the body is a reminder for that. model accepts sonnet, opus, haiku, fable, a model ID, or inherit (same as the main conversation). How to choose a model per subagent is covered in "How to run Claude Code subagents on a different model".

The concurrency limit and nesting depth are set with environment variables, which you can put under env in settings.json.

{
  "env": {
    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "5",
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"
  }
}

Sources: Anthropic "Create custom subagents", "Orchestrate teams of Claude Code sessions". Checked October 26, 2026.

5. Command reference

These are the commands for watching running subagents, separating working copies, branching a conversation and so on. Some share a name but do different things, so be careful.

Sources: OpenAI "Command line options, Slash commands", "Subagents"; Anthropic "Commands", "Run agents in parallel", "Create custom subagents" (trying multiple approaches with forks). Checked October 26, 2026.

The confusing one is /agents, because the names match. In Codex, /agents is the list of chats on the server (the command center). In Claude Code, /agents points you to where subagent definitions live, and the session list is claude agents (launched from the shell).

6. Tasks that suit parallel work, and tasks that don't

The two sets of official docs say almost the same thing: start with read-only work, and be careful with write-heavy work.

Sources: OpenAI "Subagents" (Why subagent workflows help); Anthropic "Create custom subagents" (Choose between subagents and main conversation) and "agent teams" (Avoid file conflicts). Checked October 26, 2026.

7. Impact on cost (usage limits)

Going parallel is faster, but it uses more of your usage, because each subagent makes its own model calls and uses its own tools.

Sources: OpenAI "Subagents", "Changelog"; Anthropic "Manage costs effectively", "Create custom subagents". Checked October 26, 2026.

Another thing that's easy to overlook is that subagents' replies also land in the main context. Claude Code's docs warn that running many subagents that return detailed results can consume a lot of the main context. Setting a return format such as "under 10 lines" helps with cost, too. General token-saving for Claude Code is covered in "Claude Code token-saving tips".

8. Lessons from running it (this site's examples)

This site (AI Arte) runs by handing article translation and checks to Claude Code subagents in parallel. The research and draft for this article were also written by one of the subagents dispatched by the main session. Below are things that actually happened, along with how to avoid them. All of these are records from Claude Code; none were reproduced in Codex. Still, same-file conflicts and inaccurate reports about things outside a subagent's scope are worth watching for in Codex too, since its mechanism is similar.

1. July 2026Set how many run at once to fit your own limits

   What happened

   Running six or more at once caused subagents to fail on rate limits

   How to avoid

   Cap it at 5 at once, and run larger jobs in batches of 5 in turn. Set a cap that fits your own limits, below Claude Code's default cap (20)

2. September 22, 2026Don't let subagents spawn more subagents

   What happened

   A subagent handed a 10-language job spawned 5 translation subagents of its own. Together with the parent's 5, that made 10 running at once, hit the usage limit, and every one of them stopped midway

   How to avoid

   Under "what not to do" in the instructions, write "Don't spawn subagents. The parent assigns the work." Claude Code lets subagents spawn subagents by default (up to 3 levels), so you can also stop nesting with CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1

3. August 22, 2026Never let two subagents touch the same file

   What happened

   A sentence the parent had added to the end of a course chapter was deleted by another subagent as "not in the instructions," then re-added, over and over

   How to avoid

   Assign each subagent the files it may touch. For anything the parent will add in bulk later, either mention it in the subagents' instructions too, or add it after everyone has finished

4. September 22, 2026Separate where temporary files go, too

   What happened

   A temporary script one subagent placed directly in the scratch folder had been overwritten by another subagent's file with the same name. Subagents spawned from the same conversation see the same scratch folder

   How to avoid

   In the instructions, assign each subagent its own subfolder

5. September 5, 2026Don't commit everything at once while subagents are running

   What happened

   While 5 were running, an unrelated change was committed with git add -A (all changes), sweeping 100 files the subagents had finished into an unrelated commit

   How to avoid

   Commit by specifying files. Also tell subagents that operations that bundle all changes or revert changes are prohibited

6. August 22, 2026Re-measure anything subagents report outside their own scope

   What happened

   Two subagents reported "24 items fail the check" and "28," but the actual count was 16. They had guessed at the state of files they hadn't touched

   How to avoid

   The parent verifies counts and targets by running the checks itself. Findings within a subagent's own scope are highly accurate, so those can be trusted

Taken from this site's operating records (July to September 2026). Only numbers that remain in those records are included.

Putting these lessons together, the instructions you hand out look like this. Subagents don't know the rest of the conversation, so write it so that the instructions alone are enough to finish the job.

[Task] Research article 273 and write the ja draft
[What not to do]
- git operations (add, commit, checkout, restore, stash, push)
- Don't spawn subagents (the parent assigns the work)
- Don't edit other articles
- Put temporary files in scratch-folder/a273/
[How to research] From the original text of the official docs (record URLs and check dates)
[What to return] Files created, title, anything that couldn't be verified

The skeleton (summarized) of the instructions the subagent that wrote this article received, plus two of the lessons above (don't spawn subagents, where to put temporary files). The same format works for instructions to subagents in both Codex and Claude Code.

Summary

For the overall differences between the two tools (pricing, limits, where they run), see "Claude Code vs Codex: Which Should You Choose?", and for settings that bring subagents closer to read-only, see "How to Use Codex and Claude Code Read-Only".

FAQ

Q. How many Codex subagents can run at once?

A. You set the cap with agents.max_concurrent_threads_per_session in config.toml (the main thread isn't counted). If you leave it out, Codex decides, and that default value isn't published. The official configuration examples use 6 or 8. Claude Code's default is 20 at once, changeable with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. With either tool, the more you run, the faster your usage limits drain.

Q. Can I use a cheaper model just for subagents?

A. Yes. In Codex, set it with default_subagent_model under [agents], or with model and model_reasoning_effort in the agent file. If unspecified, the parent's model is inherited. In Claude Code, set model in the subagent definition (haiku, etc.) or use the CLAUDE_CODE_SUBAGENT_MODEL environment variable.

Q. Do I need to write "multi_agent = true" in my config?

A. Not in current Codex. In the configuration reference, features.multi_agent is stable and on by default, and agents.enabled also defaults to true. Per the changelog, multi-agent V2 arrived as an opt-in system and became stable in Codex CLI 0.145.0 (July 21, 2026). The "enable it" steps in older guides now produce the same state as writing nothing. To turn it off, write enabled = false under [agents].

Q. How do I stop Claude Code from spawning subagents on its own?

A. To block subagents entirely, add Agent to permissions.deny in your permission settings. To stop only the conversation-inheriting subagents (forks), use Agent(fork) or the environment variable CLAUDE_CODE_FORK_SUBAGENT=0. If agent teams are enabled, a named subagent may start as a team member, so leave agent teams disabled if you don't use them.