Codex

Subagents and worktrees

Split independent investigation, review and implementation tasks without conflicting edits.

Use one thread for straightforward tasks. Add subagents or worktrees when the task separates into independent investigation, review, testing or implementation units.

Subagents consume additional usage and worktrees consume disk space. Do not parallelize edits that depend on the same files without isolation.

#Choose a capability

Goal	Capability	Example
Parallel reading/review	Subagents	Security, test gaps, architecture and logs
Background branch implementation	Worktree	Continue local work while another checkout experiments
Long-running independent direction	Persistent worktree	Refactor, upgrade or spike branch
Move between foreground/background work	Handoff	Bring a background result into local inspection
Reusable team responsibilities	Custom agents	Reviewer, tester, explorer or migration owner

#Subagents

Request delegation explicitly and specify roles, boundaries and how to combine results:

Review this branch with three parallel subagents:
1. Security and permission risks.
2. Missing tests and regression risks.
3. Maintainability and unnecessary complexity.
Wait for all results, then consolidate P0/P1/P2 findings with file paths and reasons.

Task	Why delegation helps
Large repository exploration	Independent domains reduce main-thread noise
PR review	Different perspectives inspect security, correctness and tests
Failure investigation	Separate logs, CI and recent changes
Documentation audit	Separate source coverage from navigation/link checks

Avoid delegation when:

Several workers would rewrite the same core file.
Requirements remain too ambiguous to coordinate.
A small task costs less than parallel setup and integration.

#Custom agents

Personal definitions live under ~/.codex/agents and project definitions under .codex/agents. A representative TOML role:

name = "reviewer"
description = "Review code for correctness, security, regressions, and missing tests."
developer_instructions = """
Prioritize concrete bugs over style.
Return findings with file paths and severity.
Do not modify files.
"""
model_reasoning_effort = "high"
sandbox_mode = "read-only"

Field	Purpose
name	Stable role identifier
description	When the role should be selected
developer_instructions	Behavior and output requirements
model	Optional available model override
model_reasoning_effort	Supported effort appropriate for the task
sandbox_mode	Read-only for a non-editing reviewer
mcp_servers	Role-specific tool configuration where supported

Concurrency settings:

[agents]
max_threads = 6
max_depth = 1
job_max_runtime_seconds = 1800

Keeping max_depth at 1 limits nested delegation. Check resource and usage needs before raising it.

#Worktrees

An app-managed worktree is an independent Git checkout for background work.

Prerequisites:

A Git repository.
Dependencies and environment reproducible in another checkout.
Explicit handling of ignored local files required by the task.

Example .worktreeinclude:

.env.local
config/secrets.json

Only include files that are genuinely needed and authorized for that checkout. Do not automatically copy an entire credential directory or list tracked files unnecessarily.

#Handoff

Direction	Purpose
Local to worktree	Release the current directory for other work
Worktree to local	Inspect with local IDE, test setup or dev server
Worktree to branch	Prepare a commit, push or PR

Git generally prevents checking out one branch in two worktrees. Let the supported handoff workflow handle necessary branch operations rather than forcing conflicting checkouts.

#Parallel work practices

Item	Recommendation
Branch names	codex/task or spike/task
Permissions	Read-only for exploration; workspace-write for authorized implementation
Dependencies	Install per worktree without altering unrelated lockfiles
Verification	Run relevant checks before integration
Merge	Inspect diff before cherry-pick/merge/PR
Cleanup	Remove unneeded checkouts after preserving valuable work

#Passion8 boundary

Supported local CLI/app/IDE workflows can use https://passion8.cc/v1. Hosted cloud tasks and official integrations have their own provider and account configuration; they do not inherit the local files automatically.

#Continue reading

Git and GitHubBranches, commits, worktrees and recovery.Review workflowsLocal, hosted and CI reviews.PermissionsScope each worker

#Official references

PreviousHooks, rules and customization NextAutomation and cloud runs

Support

Need help?

For setup, billing, or model issues, email us. Check the status page for uptime.

Support Email[email protected]Service Statusstatus.passion8.cc

WeChat / QQ support is available at the bottom right.