Skip to content

Codex vs Claude Code: The Divergence in Subagent Design Philosophy

For / Key Points

Audience: Engineers actively using or evaluating AI coding agents for production work. Assumes familiarity with basic Codex CLI or Claude Code operations.

Key Points:

  • Frames the design divergence as a difference in "trust model," giving you a clear axis for tool selection
  • Structurally compares Codex (explicit spawn + TOML) and Claude Code (implicit delegation + Markdown)
  • Provides selection criteria based on audit requirements, team AI literacy, and workflow structure

Why Subagents Became Necessary

The question this section answers

What are the limits of a single agent, and what problems do subagents solve?

Running AI coding agents on large codebases hits three bottlenecks.

  1. Context pollution — file exploration dumps massive text into the main conversation window, crowding out tokens needed for implementation decisions
  2. Sequential execution speed — investigating auth modules, checking DB schemas, and scanning API patterns are independent tasks that take 3x wall time when run serially
  3. Coarse permissions — exploration-only tasks get full write access, making safety harder to guarantee in production codebases

Subagents solve all three simultaneously. The main agent acts as an orchestrator, delegating individual investigation and implementation tasks to subagents that each have their own context window. Exploration noise stays contained within the subagent; only a summary returns to the parent. Independent tasks run in parallel, and read-only subagents receive no write tools, enforcing least-privilege12.

This structure is known as the orchestrator + subagent pattern. Claude Code implemented it as the Agent tool (formerly Task) starting in late 20252. Codex enabled subagent workflows by default in its mid-March 2026 release, documenting them as a stable feature1. Both major AI coding agents have now officially adopted this pattern.

So where exactly do their designs converge, and where do they diverge?

Architecture Comparison: Where Designs Diverge

The question this section answers

What specific design decisions do the two tools share, and where do they differ?

Shared Design Principles

The design decisions both tools share represent structural convergence, not superficial similarity.

Context isolation. Each subagent has its own context window, and intermediate tool call results do not flow back to the parent. The parent receives only the final message (summary). This prevents exploration costs from crowding the main context12.

Read-focused agent standardization. Codex's explorer is designed as a "read-heavy" exploration agent, with sandbox_mode available to enforce read-only access1. Claude Code's Explore explicitly denies access to Write and Edit tools2. Both are intentional constraints for running parallel exploration safely on production codebases.

Custom agent definitions. Both support defining custom agents at the project or user scope, with individual model selection, tool restrictions, and dedicated prompts.

With the shared skeleton clear, here are the four design decisions where the tools diverge.

Divergent Design Decisions

Who decides when to delegate?

Claude Code subagents use implicit delegation as the default. The main agent matches task characteristics against subagent description fields and automatically selects the appropriate subagent2. Without any explicit instruction, the Plan subagent activates in planning mode and the Explore subagent activates for codebase exploration.

For explicit invocation, natural language instructions and @-mentions for session-scoped selection are also available2.

Codex takes the explicit spawn approach. Subagents do not start unless the user writes something like "Spawn one agent per point" in the prompt1. This design prioritizes predictability of token consumption.

# Typical spawn prompt in Codex
Spawn one agent per point, wait for all of them,
and summarize the result for each point.
1. Security issue
2. Code quality
3. Bugs

A subagent launches only when the user writes "spawn." In Claude Code, passing an equivalent task may trigger the Agent tool automatically based on the agent's own judgment.

How are agents defined?

AspectCodexClaude Code
Definition formatTOMLMarkdown + YAML frontmatter
Project location.codex/agents/.claude/agents/
User location~/.codex/agents/~/.claude/agents/
Required fieldsname, description, developer_instructionsname, description (body = prompt)
Model overridemodel field (inherits from parent if omitted)model field (inherits from parent if omitted)
Permission controlsandbox_mode per-agent overridepermissionMode with 5 levels

Codex adopts TOML following infrastructure configuration conventions, separating developer_instructions as an explicit field1. Claude Code uses the Markdown body itself as the system prompt, unifying documentation and agent definition2.

How much control over parallelism?

Codex sets agents.max_threads to 6 and agents.max_depth to 1 (direct children only, no recursive nesting) by default, as documented officially1. For batch processing, spawn_agents_on_csv (experimental) launches one worker per CSV row. Each worker reports results via report_agent_job_result, with state managed in SQLite1.

On the Claude Code side, public settings directly corresponding to Codex's max_threads/max_depth are not prominently documented. Practical parallelism control relies mainly on prompt engineering (explicit instructions like "launch 5 subagents in parallel").

However, Claude Code offers Agent Teams (experimental) — a separate parallelism layer where multiple independent Claude Code sessions cooperate peer-to-peer via shared task lists and mailbox messaging3.

Can agents talk to each other?

Codex's latest release (March 26, 2026, multi-agent v2) assigns path-based addresses to subagents (e.g., /root/agent_a) and introduces structured inter-agent messaging4. Steering instructions can now be sent to running subagents during execution.

Claude Code's subagent communication is currently parent-to-child one-way. The parent passes context via the Agent tool's prompt string, and the child returns results in its final message2. Agent Teams (multi-session) enables peer-to-peer communication through shared task lists and mailbox messaging, but this differs in nature from Codex's structured messaging3.

Built-in Agent Roster

RoleCodexClaude Code
Read-only explorationexplorerExplore (Haiku model)
General executiondefaultGeneral-purpose
Implementation-focusedworker— (general-purpose covers this)
Planning-focused—Plan (auto-activates in plan mode)
Batch processingspawn_agents_on_csv (experimental)—
Bash execution—Bash (context isolation)

Codex explicitly separates worker as a write-enabled execution role1. Claude Code has a Plan subagent dedicated to the planning phase2. This difference suggests that Codex organizes subagents around task execution units, while Claude Code organizes them around thinking phases.

Practical Selection Criteria

The question this section answers

In what use cases does each subagent design have the advantage?

Where Codex Has the Edge

Batch processing and routine audits. Picture a CI/CD job that checks dependencies across 100 repositories weekly. spawn_agents_on_csv specializes in "launch one worker per CSV row with the same prompt, export results to CSV" workflows (experimental)1. It excels when inputs are structured — security audits, bulk migration checks.

Token cost predictability. The explicit spawn model means no unintended subagent launches. When running on pay-per-token APIs, cost management becomes straightforward.

Cloud-native workflows. Codex was designed for cloud sandbox execution from the start. Non-interactive execution via codex exec from CI/CD pipelines fits naturally.

Where Claude Code Has the Edge

Exploratory, interactive development. Imagine prototyping a new feature with the design direction still undecided. Implicit delegation means users get the optimal agent without thinking about subagents. The Plan subagent auto-activating in plan mode makes the think → implement flow seamless2.

Automatic context optimization. The Explore subagent defaults to a lightweight model (Haiku), implicitly optimizing read-exploration costs. The main session runs Opus for complex reasoning while exploration delegates to Haiku — no configuration needed2.

Lifecycle control via Hooks. Attaching hooks to SubagentStart/SubagentStop events enables custom logic at subagent launch and termination5. For example, sending a Slack notification on subagent start or aggregating logs on termination.

Summary

Both tools sharing the skeleton of "orchestrator + read-only exploration agent + write-enabled execution agent" is a verifiable fact when comparing official documentation side by side12. The multi-agent architecture pattern for AI coding agents is solidifying.

However, what's standardized is the pattern skeleton — control granularity diverges. Codex moves toward "programmable orchestration" with structured messaging (multi-agent v2) and batch processing (CSV fan-out). Claude Code moves toward "autonomous team coordination" with Agent Teams and shared task lists.

The core of this divergence is a difference in where operational responsibility lies. In Codex, users explicitly design subagent launch timing, parallelism, and nesting depth. Fan-out design is the user's responsibility, yielding higher auditability and predictability. In Claude Code, the agent itself judges task characteristics and selects delegation targets. Cognitive load decreases, but post-hoc tracking requires supplementary mechanisms like Hooks5.

In short, Codex places the user's explicit instructions as the trust anchor, while Claude Code places the agent's own judgment as the trust anchor. Projects with strict audit requirements and structured workflows favor Codex's explicitness; exploratory, interactive development phases favor Claude Code's autonomy.

Where this "trust model" divergence will be tested next is in the standardization of inter-agent protocols. Frameworks for cross-vendor agent cooperation are emerging — Google's A2A (Agent-to-Agent) and Anthropic's Model Context Protocol, for example. When agents from different vendors need to cooperate, whether the predictability of explicit spawning or the flexibility of implicit delegation proves more compatible with protocol design will become the next watershed in architectural decisions.

Post this article Copy link

  1. OpenAI, "Subagents – Codex", OpenAI Developers https://developers.openai.com/codex/subagents — Documents explicit spawn model, built-in agents (default/worker/explorer), TOML definitions, agents.max_threads/agents.max_depth defaults, spawn_agents_on_csv, and sandbox inheritance. ↩↩↩↩↩↩↩↩↩↩↩

  2. Anthropic, "Create custom subagents", Claude Code Docs https://code.claude.com/docs/en/sub-agents — Documents description-based auto-delegation, built-in subagents (Explore/Plan/General-purpose), Markdown + YAML frontmatter definitions, Explore model (Haiku) and tool restrictions, permissionMode. Note: the tool used for subagent invocation was formerly called Task, now Agent. ↩↩↩↩↩↩↩↩↩↩↩↩

  3. Anthropic, "Agent teams", Claude Code Docs https://code.claude.com/docs/en/agent-teams — Documents multi-session peer-to-peer coordination, shared task lists, and mailbox messaging. ↩↩

  4. OpenAI, "Codex Changelog", OpenAI Developers https://developers.openai.com/codex/changelog — Documents the March 26, 2026 release with multi-agent v2 (path-based addressing, structured inter-agent messaging). ↩

  5. Anthropic, "Control execution with hooks", Claude Code Docs https://code.claude.com/docs/en/hooks — Documents Hooks lifecycle including SubagentStart/SubagentStop events. ↩↩