How to Name and Manage Codex Subagents

When one Codex task becomes complicated, it can help to divide the work among subagents. One agent can explore the project, another can implement an approved change, and a third can review the result. The main Codex task coordinates them and combines their findings.

Names make this system understandable, but a name is only an identity. Calling an agent read_only_reviewer does not technically make it read-only. Its effective authority comes from the workspace, sandbox, permission mode, available tools, and approvals.

Agent role
    = name + description + instructions

Agent authority
    = visible workspace + sandbox + permissions + tools + approvals

What is a subagent?

A subagent is a specialized agent that the main Codex task starts for a bounded assignment. The main task acts as the coordinator: it divides the work, gives each subagent context, waits for the results, and produces the final response.

You
 ↓
Main Codex task — coordinator
 ├── project_explorer
 ├── implementation_worker
 └── change_reviewer
          ↓
Coordinator verifies and combines the results
          ↓
You approve consequential actions

Current Codex releases include built-in roles named default, worker, and explorer. Local Codex clients also support custom agents with their own names and instructions. Availability and interface details can vary by client, version, account, and workspace policy.

Name agents by responsibility

A useful name answers, “What job should I expect this agent to perform?” Prefer role names over personalities or sequence numbers.

Good names
project_explorer
documentation_researcher
dependency_auditor
implementation_worker
test_runner
change_reviewer
release_checker

Weak names
agent_one
helper
smart_agent
bob

A simple convention is object_function:

project_explorer explores a project;
code_reviewer reviews code;
article_researcher researches an article;
publication_checker checks publication readiness.

Use the same role for repeated assignments. If three projects need inspection, you do not need three different role definitions. Spawn three instances of project_explorer and label their assignments clearly: Blog Desk explorer, ChatHub explorer, and ETF explorer.

The four parts of an agent definition

A custom agent is easiest to understand when you separate four concerns:

Name: the identifier Codex uses when spawning or referring to the agent.
Description: human-facing guidance explaining when the role is appropriate.
Developer instructions: the job, boundaries, working method, and expected output.
Sandbox setting: an optional technical restriction, such as read-only access.

OpenAI's current custom-agent schema requires name, description, and developer_instructions. Other supported configuration settings, including sandbox_mode, model settings, MCP servers, and skills configuration, can also be included.

Where custom agents live

Use project-scoped agents when the roles belong to one repository:

Control-Center\
└── .codex\
    ├── config.toml
    └── agents\
        ├── project-explorer.toml
        ├── implementation-worker.toml
        └── change-reviewer.toml

Use personal agents when you want the roles available across your local Codex projects:

C:\Users\YourName\.codex\agents\

The filename may differ from the agent name, but matching them is easier to maintain. The name field inside the file is the source of truth.

Define a read-only explorer

An explorer is a good first custom role because exploration is independent, evidence-heavy work that benefits from parallel execution.

name = "project_explorer"
description = "Read-only agent that inspects one assigned project and returns evidence."
sandbox_mode = "read-only"

developer_instructions = """
Inspect only the project assigned by the coordinating agent.

Report:
1. Project purpose
2. Languages and frameworks
3. Repository structure
4. Current Git status
5. Major dependencies
6. Reusable modules
7. Duplicate functionality
8. Security or maintenance concerns

Do not edit files, install software, copy secrets, commit, push,
publish, deploy, or inspect unrelated projects.

Return a concise report with file references to the coordinator.
"""

The name makes the role recognizable. The instructions define its expected behavior. The read-only sandbox is the technical control that prevents file modification within the applicable environment.

Define a carefully bounded worker

A worker performs implementation. Because write work has more impact, its instructions should name the target, require a clean scope check, and define verification.

name = "implementation_worker"
description = "Implements an approved change in one explicitly assigned project."

developer_instructions = """
Modify only the project and files assigned by the coordinator.

Before editing:
1. Read the applicable AGENTS.md instructions.
2. Check Git status.
3. Identify unrelated existing changes.
4. Confirm the permitted files.

After editing:
1. Run the relevant tests or build.
2. Report every changed file.
3. Report verification results.

Do not modify another project, commit, push, deploy, or publish
unless that exact action is separately authorized.
"""

If the parent workspace contains several writable projects, instructions alone do not create strict filesystem isolation. For sensitive changes, open only the target project or otherwise narrow the workspace's writable boundary.

Define an independent reviewer

name = "change_reviewer"
description = "Read-only agent that reviews changes made by another agent."
sandbox_mode = "read-only"

developer_instructions = """
Review the assigned changes without editing them.

Check:
- correctness
- requested-scope compliance
- unintended file changes
- security and privacy risks
- possible regressions
- missing tests
- verification results

Lead with concrete findings and include file references.
Return the review to the coordinator.
"""

Separating implementation and review reduces self-review bias. The reviewer should inspect evidence, not merely repeat the worker's summary.

Configure the number of agents

Project-level agent settings can live in .codex/config.toml:

[agents]
enabled = true
max_concurrent_threads_per_session = 4

Current Codex releases enable multi-agent tools by default, so explicitly setting enabled = true is often unnecessary. A concurrency limit can still prevent an unexpectedly large group of agents from running at once. Each subagent does its own model and tool work, so additional agents also use additional tokens.

Tell the coordinator exactly how to delegate

A strong delegation prompt identifies the roles, divisions of work, synchronization point, and final output.

Act as the coordinating agent.

Spawn three project_explorer subagents:
1. Inspect Blog-Desk only.
2. Inspect ChatHub only.
3. Inspect ETF-Pair-Finder only.

Keep all three read-only and run them in parallel.
Wait for all three agents to finish.
Then compare their findings in one table.

Do not modify, commit, push, publish, or deploy anything.

For a controlled implementation:

Use project_explorer to inspect the target project first.
Wait for its report and propose a change.

After I approve the proposed files and approach,
use implementation_worker to make the change.

Then use change_reviewer to review the completed diff.
Run final verification and return one consolidated report.

Do not commit or push.

Names do not grant rights

This is the most important rule in agent management:

Name describes identity.
Description supports selection.
Instructions define responsibility.
Sandbox and workspace define authority.

Subagents generally inherit the parent task's active sandbox and permission mode. Codex also reapplies live runtime permission choices from the parent turn when spawning a child. A custom agent can specify a narrower sandbox such as read-only, but you should verify the actual environment instead of assuming the role name provides protection.

Filesystem access is also separate from GitHub access, network access, connected applications, and deployment authority. A worker that can edit local files does not automatically have permission to push, publish, or operate an external service.

Start with read-heavy parallel work

Parallel subagents are especially useful for exploration, documentation research, test analysis, triage, and summarization. Each agent can investigate one independent question while the coordinator protects the main task from excessive intermediate output.

Be more cautious with parallel writing. Two workers editing the same file or closely related code can conflict, invalidate each other's assumptions, and make the final review harder.

Safer
├── Explorer A reads Project A
├── Explorer B reads Project B
└── Reviewer analyzes an existing diff

Riskier
├── Worker A edits shared-file.ts
└── Worker B edits shared-file.ts at the same time

A good default is many readers, one writer, and one independent reviewer.

Monitor and steer the agents

Supported Codex clients show subagent activity and let you inspect individual agent threads. In the CLI, /agent can switch among active agent threads. In the desktop app or IDE, use the available subagent or background-agent panel to inspect status and results. You can also tell the coordinator to steer a running agent, stop it, or close completed threads.

Do not judge progress only by an agent's name. Open its thread when the assignment is consequential, inspect the evidence it returns, and require the coordinator to reconcile conflicting findings.

Common mistakes

Treating the name as a permission: read_only_agent is not read-only unless the environment enforces it.
Giving every agent a unique personality: reusable roles are easier to understand and audit.
Writing vague descriptions: state when the coordinator should and should not use the role.
Assigning overlapping write tasks: parallel edits create conflicts and coordination costs.
Skipping the wait instruction: tell the coordinator whether it must collect every result before continuing.
Returning raw output: require concise findings, evidence, and file references.
Allowing automatic publication: separate drafting, review, commit, push, and deployment approvals.

A practical management model

1. Coordinator receives the objective
2. Explorers gather evidence in parallel
3. Coordinator compares their findings
4. Coordinator proposes a plan
5. User authorizes one target and scope
6. One worker implements the change
7. One reviewer inspects the result
8. Coordinator runs final verification
9. User separately authorizes commit or publication

The best agent system is not the one with the most agents. It is the one where every role has a clear purpose, every assignment has a boundary, every result has evidence, and every consequential action still has an owner.

Official references

More Codex Learning →