Subagent on KnightLi Blog

Codex vs Claude Code: How to Choose Between Two Subagent Designs

Fri, 08 May 2026 14:14:01 +0800

AI coding tools are paying more attention to subagents. This is not just feature chasing. A single agent eventually hits limits when it has to handle real engineering work.

If one agent reads code, checks logs, edits implementation, runs tests, analyzes failures, and summarizes results at the same time, the main context quickly becomes noisy. Search results, command output, test logs, and intermediate reasoning get mixed together. Later decisions become less reliable. Work also becomes hard to parallelize: exploration, implementation, verification, and review all sit on one main thread.

The purpose of subagents is to reduce that pressure. The main session stops doing everything from start to finish and becomes more like a coordinator: define goals, assign work, receive results, and merge them into the final answer. A subagent handles a local piece of work, such as exploration, implementation, verification, or review, and returns a compressed conclusion.

So a subagent is not “another copy of me.” It is a way to split tangled engineering work into clearer roles.

Shared Foundations

A mature subagent system usually needs four foundations:

Context isolation.
Role specialization.
Project and user-level configuration.
Tool and permission boundaries.

Context isolation comes first. Real repositories produce a lot of intermediate material: dozens of search hits, hundreds of test log lines, noisy command output. If all of that is poured into the main session, the main thread gets confused. A subagent can digest that local process and bring back only the signals that matter.

Role specialization is just as important. Multi-agent does not mean opening several identical models. Exploration roles should search, read, and summarize. Implementation roles should focus on local code changes. Verification roles should run checks, identify risks, and report clearly.

Tool and permission boundaries determine whether the system can be used safely. A subagent should not automatically inherit every capability of the main session. A read-only explorer does not need write access. A verifier may not need to change implementation. Background tasks and isolated worktrees need visible boundaries.

Codex and Claude Code share these concerns, but they take different routes.

Codex: Explicit Delegation

Codex’s subagent design feels restrained.

It gives you a controlled, lightweight delegation mechanism around the current main session. When to delegate, who receives the task, and when results are collected are all explicit decisions. The control flow stays in the current task.

Its traits are clear:

The main session explicitly delegates subwork.
The role set stays small.
The main session knows which agent is doing what.
Results return to the main line for final judgment.
Collaboration boundaries are transparent.

This works well for teams that care about manual orchestration, predictability, and execution determinism. You can ask an explorer to inspect a call chain, ask a worker to make a bounded change, then let the main session merge the result and decide whether to test further.

The tradeoff is that orchestration pressure still sits with the main session. The main thread must decide when to split work, how to split it, who should take it, and how to merge the result. For lightweight collaboration this is pleasant; for long-running engineering workflows it can become tiring.

Claude Code: Agents as Workstations

Claude Code takes a more platform-like route.

It treats agents as describable, selectable, configurable, memorable, isolated, and background-capable objects. A subagent is not just a helper in a conversation. It is closer to a workstation in an engineering system.

The system can expose agent lists, use cases, descriptions, and tool boundaries to the model, allowing the model to decide which role should handle a turn. That makes delegation more automatic.

Several capabilities define this direction.

First, a role system. Explorer, planner, general-purpose, and verifier roles can carry usage descriptions, tool restrictions, default models, and runtime conditions. A read-only explorer can be prevented from editing files. A planner can focus on architecture. A verifier can focus on checks.

Second, inheritance and overrides. A subagent is not completely free. It inherits the larger boundary of the main session by default, but can adjust local behavior within allowed rules. The main session defines the big boundary; the agent performs local assembly inside it.

Third, memory. Memory is not just “remember a few things.” It can have scope. User memory is like long-term preference. Project memory is repository background. Local memory is environment-specific state. This lets some agents avoid relearning the project from scratch.

Fourth, background work and worktree isolation. Some verification tasks can keep running in the background, while the main thread continues. When stronger isolation is needed, an agent can work in a separate worktree, keeping the project connected but the operation space separated.

Fifth, plugin ecosystem. If agents are first-class objects, you have to think about distribution, installation, priority, override rules, and safety. Plugin agents can enter the system, but high-risk fields such as permission mode, hooks, and MCP servers should remain guarded.

This makes Claude Code feel more like an agent runtime than a one-session collaboration tool.

The Difference

Codex is closer to a controlled delegation tool:

Explicit delegation.
Lightweight role set.
Clean control flow.
Subtasks centered on the current session.
Good for deterministic, human-orchestrated work.

Claude Code is closer to an engineering workstation system:

Agents are formally modeled.
Roles are more systematic.
Memory, background execution, isolation, and plugins are part of the runtime.
The model can help choose roles.
Good for long-term projects and platform-like workflows.

The real question is not which one has more features. It is whether you want a subagent to be “a helper I explicitly call” or “a long-lived workstation in the system.”

How to Choose

Choose the Codex style if you value explicit control, lightweight delegation, and safe parallelism inside the current session. It is good for code review, small changes, clearly scoped implementation tasks, and workflows where a human wants to keep the rhythm.

Choose the Claude Code style if you want systematic roles, long-term memory, background execution, worktree isolation, plugin extension, and a more complete agent runtime.

Ask two questions:

Are you comfortable with the model choosing who should do the work?
Do you need a fuller agent runtime?

If the first question makes you uncomfortable, explicit delegation is likely better. If the second answer is yes, a platform-like workstation system may fit better.

Practical Advice

Do not treat subagents as “more models means stronger.” Better practice is:

Give every role a clear task boundary.
Limit the tools each role can use.
Ask subagents to return conclusions, not raw logs.
Keep final decisions in the main session.
Make background tasks and worktree isolation visible.
Set clear safety boundaries for plugin agents.

The value of subagents is not quantity. It is clean division of labor, cleaner context, and more stable main-thread decisions.

Summary

Codex and Claude Code solve the same problem: one agent cannot comfortably carry all real engineering work. Both recognize the importance of context isolation, role specialization, permissions, and local summarization.

Codex is more restrained, emphasizing explicit delegation and main-session control. Claude Code is more systematic, treating agents as configurable, memorable, isolated, background-capable workstations that can also enter a plugin ecosystem.

The choice is not which brand wins. It is whether your workflow needs a controlled collaboration tool or a full agent runtime.

Claude Code Multi-Agent Collaboration: How to Choose Between Subagents and Agent Teams

Wed, 22 Apr 2026 21:35:52 +0800

When people talk about multi-agent collaboration in Claude Code, the easiest two concepts to mix up are Subagents and Agent Teams. They both sound like “spin up several agents to work together,” but they are meant for different kinds of work. In short, the former is better for splitting off independent tasks, while the latter is better when several agents need to collaborate around the same problem and cross-check each other over time.

If you have used Skills before, this framing also helps:

A Skill defines the workflow and rules
A Subagent or Agent teammate does the actual execution

So the real question is not which one is “more advanced,” but what kind of collaboration problem you are solving.

Subagents: split off side tasks

Subagents are closer to temporary worker copies launched from the current session. Each one gets its own context window, and when it finishes, it returns only a summary of the result. The main conversation stays cleaner because it does not have to absorb all the intermediate logs and output.

That gives Subagents a few very practical strengths:

The main thread stays clean instead of being flooded by test logs, search results, or long output
Independent research or execution tasks can run in parallel
They work well for tasks where “just bring me the result” is enough

The original article notes that Claude Code comes with three built-in kinds of Subagents:

Explore: read-only, useful for quickly searching a codebase
Plan: read-only, useful for gathering information in the background during plan mode
General-purpose: can read and write, suitable for tasks that mix exploration and editing

Custom Subagents

If the built-in options are not enough, you can define your own Subagent. The mechanism is simple: write a Markdown file in one of these locations:

.claude/agents/: only active in the current project
~/.claude/agents/: active across all your projects

The file format looks like this:

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:

1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:

- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:

- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

The key field here is description. Claude uses it to decide when this Subagent should be called, so the more precise the description is, the more reliable the trigger tends to be.

A few other common configuration fields are also worth knowing:

tools: limits which tools the Subagent can use
model: chooses between sonnet, opus, haiku, or inherit
permissionMode: controls edit permissions and permission prompt behavior
memory: gives the Subagent a cross-conversation memory directory

If you only need a Subagent temporarily, you can also define it through the CLI:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

When Subagents fit best

Subagents are usually the best fit for tasks like these:

Running tests and returning only the failure summary instead of flooding the main thread with thousands of log lines
Investigating several unrelated modules in parallel
Splitting “find the issue” and “fix the issue” into a simple pipeline

For example:

`1`	`Research the authentication, database, and API modules in parallel using separate subagents`

`1`	`Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them`

But if a task needs constant back-and-forth adjustments, shares a lot of context across stages, or concentrates changes in only one or two files, handling it directly in the main conversation is often simpler than spinning up a Subagent.

Agent Teams: multiple independent sessions working together

Agent Teams operate at a different level. Instead of launching worker copies inside one session, they start multiple fully independent Claude Code instances that collaborate around a shared task list and can also message one another directly.

That makes an Agent Team feel more like a real small team than a simple side-task worker setup.

The article notes that this is currently an experimental feature and needs to be enabled first:

{
    "env": {
        "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
    }
}

Once this is added to settings.json, you can ask Claude to organize a team around a specific goal. For example:

1
2
3

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

What an Agent Team consists of

An Agent Team mainly includes three parts:

Team lead: the main session you are using, responsible for organizing, assigning, and summarizing
Teammates: multiple independent Claude Code instances
Task list and Mailbox: the shared task list and communication channel

The biggest difference from Subagents is that teammates can communicate directly with one another instead of routing everything through the lead. Tasks usually move through states such as pending, in progress, and completed, and once a teammate finishes one task, it can pick up the next one.

When Agent Teams fit best

When a task needs several perspectives, active discussion, conflicting hypotheses, or parallel work across modules, Agent Teams are a better fit.

The article gives several representative examples:

Several reviewers inspect the same PR in parallel, each focusing on a different dimension
Multiple agents investigate the same bug with competing explanations and challenge each other’s conclusions
Frontend, backend, and testing move forward in parallel on different parts of the project

For example, parallel code review:

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

And for debate-style debugging:

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

The common pattern here is that you do not just want one answer. You want several agents to exchange judgments, challenge assumptions, and gradually converge on a stronger conclusion.

How to choose between them

If you want a quick rule of thumb, use this:

If you just need the result, use Subagents
If the work requires discussion and cross-validation, use Agent Teams

Expanded a bit further, the main differences are:

Communication style: Subagents mainly report results back to the main session, while Agent Teams members can talk directly to one another
Coordination model: Subagents depend more on the main conversation to orchestrate them, while Agent Teams work from a shared task list that members can claim themselves
Token cost: Subagents are cheaper, while Agent Teams cost more because each teammate is an independent instance
Best-fit tasks: Subagents are better for independent, result-oriented work, while Agent Teams are better for discussion-heavy and cross-check-heavy work

Practical cautions

Agent Teams are more powerful, but that does not mean every task deserves a full team. The article specifically calls out a few practical concerns:

token usage is noticeably higher
if multiple teammates edit the same file at once, overwrite conflicts become very likely
adding too many teammates increases coordination cost without guaranteeing better results

A safer default is usually:

start with 3 to 5 teammates
split tasks by module or file to avoid edit conflicts
if the lead starts doing teammate work too early, explicitly tell it to wait for the others first

The current experimental version also has a few limitations, such as:

no support for /resume and /rewind for in-process teammates
task status can lag and sometimes needs manual correction
one lead can manage only one team at a time
teammates cannot spawn child teams of their own

Short conclusion

These two features are not substitutes for one another. They solve two different collaboration problems.

If your goal is “parallelize side tasks and keep the main context clean,” start with Subagents. If your goal is “let several agents work like a small team, discuss, and cross-check each other,” then Agent Teams are the better tool.

Trying both in a real task usually makes the distinction obvious very quickly: one is optimized for context isolation and result collection, and the other is optimized for multi-perspective collaboration and ongoing interaction.

Original article: https://cloud.tencent.com/developer/article/2652960