OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add boshu2/agentops --skill codex-team
Coordinate multiple Codex agents.
npx skills add boshu2/agentops --skill codex-team
The lead orchestrates, Codex agents execute. Each agent gets one focused task. The team lead prevents file conflicts before spawning — the orchestrator IS the lock manager.
For Claude-runtime feature compatibility (agents/hooks/worktree/settings), use the shared contract at skills/shared/references/claude-code-latest-features.md, mirrored locally at references/claude-code-latest-features.md, when this skill falls back to /swarm.
Don't use when: Tasks need tight shared-state coordination. Use /swarm for dependency-heavy wave orchestration.
Select backend in this order:
spawn_agent available -> Codex experimental sub-agents (preferred)codex exec ...)skill tool is read-only (OpenCode) -> OpenCode subagents — task(subagent_type="general", prompt="<task prompt>")/swarmUses the user's default Codex model. Add -m "<model>" before -C only when you intentionally want to pin a specific model.
Flag order: --full-auto -> -C -> -o -> prompt (insert -m before -C only when overriding the model).
Valid flags: --full-auto, -m, -C, -o, --json, --output-schema, --add-dir, -s
DO NOT USE: -q, --quiet (don't exist)
When tasks span multiple repos/directories, use --add-dir to grant access:
The --add-dir flag is repeatable for multiple additional directories.
Add --json to stream JSONL events to stdout for real-time monitoring:
Key events:
turn.started / turn.completed — track progressturn.completed includes token usage fieldUse -s to control the sandbox:
| Level | Flag | Use When |
|---|---|---|
| Read-only | -s read-only | Judges, reviewers (no file writes needed) |
| Workspace write | -s workspace-write | Default with --full-auto |
| Full access | -s danger-full-access | Only in externally sandboxed environments |
For code review and analysis tasks, prefer -s read-only over --full-auto.
Break work into focused tasks. Each task = one Codex agent (unless merged).
For multi-agent work that needs interchangeable workers, file reservations, session mail, repeated passes, or tmux-backed coordination, read references/fungible-agent-coordination.md [blocked] before dispatching.
Before spawning, identify which files each task will edit. Codex agents are headless — they can't negotiate locks or wait turns. All conflict prevention happens here.
For each task, list the target files. Then apply the right strategy:
| File Overlap | Strategy | Action |
|---|---|---|
| All tasks touch same file | Merge | Combine into 1 agent with all fixes |
| Some tasks share files | Multi-wave | Shared-file tasks go sequential across waves |
| No overlap | Parallel | Spawn all agents at once |
Strategy: Parallel (no file overlap)
Codex sub-agent backend (preferred):
Codex CLI backend:
Strategy: Merge (same file)
Combine all fixes into a single agent prompt:
One agent, one file, no conflicts possible.
Strategy: Multi-wave (partial overlap)
The team lead synthesizes Wave 1 results and injects relevant context into Wave 2 prompts. Don't dump raw diffs — describe what changed and why it matters for the next task.
.agents/codex-team/git diff for changes made by each agentOutput files: .agents/codex-team/<task-name>.md
Good Codex prompts are specific and self-contained:
Include in each prompt:
For multi-wave Wave 2+ prompts, also include:
timeout param for larger tasksIf Codex is unavailable, delegate to /swarm which auto-selects the best available backend (native teams with messaging/redirect/graceful shutdown, or background tasks as last resort):
Note:
/codex-teamruns Codex CLI processes as background shell commands — this is fine (separate OS processes). For Claude agent orchestration, use/swarmwhich uses your runtime's native multi-agent primitives.
| Item | Value |
|---|---|
| Model | User's configured Codex default (-m "<model>" to pin one) |
| Command | codex exec --full-auto -C "$(pwd)" -o <file> "prompt" |
| Output dir | .agents/codex-team/ |
| Max agents/wave | 6 recommended |
| Timeout | 120s default |
| Strategies | Parallel (no overlap), Merge (same file), Multi-wave (partial overlap) |
| Fallback | /swarm (runtime-native) |
User says: Fix three bugs in auth.go, config.go, and logging.go using /codex-team
What happens:
.agents/codex-team/*.mdgit diff and testsResult: Three bugs fixed in parallel with zero file conflicts.
User says: Fix three issues in zeus.go: rename field, remove unused field, fix counter
What happens:
Result: One agent, one file, no conflicts possible.
User says: Fix auth.go, add rate limiting to auth.go + middleware.go, update config.go
What happens:
Result: Sequential wave execution prevents conflicts, context flows forward.
| Problem | Cause | Solution |
|---|---|---|
| Codex CLI not found | codex not installed or not on PATH | Run npm i -g @openai/codex or use fallback /swarm |
| Default Codex model unavailable | Account/config mismatch or unsupported default | Verify codex exec --full-auto -C "$(pwd)" "echo ok" works, or pin a supported model with -m "<model>" |
| Agents produce file conflicts | Multiple agents editing same file | Use file-target analysis and apply merge or multi-wave strategy |
| Agent timeout with no output | Task too complex or vague prompt | Break into smaller tasks, add specific file:line instructions |
| Output files empty or missing | -o path invalid or permission denied | Check .agents/codex-team/ directory exists and is writable |
codex exec --full-auto -C "$(pwd)" --add-dir /path/to/other/repo -o output.md "prompt"codex exec --full-auto --json -C "$(pwd)" -o output.md "prompt" 2>/dev/null# Decision logic (team lead performs this mentally):
tasks = [
{name: "fix spec_path", files: ["cmd/zeus.go"]},
{name: "remove beads field", files: ["cmd/zeus.go"]},
{name: "fix dispatch counter", files: ["cmd/zeus.go"]},
]
# All touch zeus.go → MERGE into 1 agenttasks = [
{name: "fix auth bug", files: ["pkg/auth.go"]},
{name: "add rate limiting", files: ["pkg/auth.go", "pkg/middleware.go"]},
{name: "update config", files: ["internal/config.go"]},
]
# Task 1 and 2 share auth.go → MULTI-WAVE (1+3 parallel, then 2)
# Task 3 is independent → runs in Wave 1 alongside Task 1tasks = [
{name: "fix auth", files: ["pkg/auth.go"]},
{name: "fix config", files: ["internal/config.go"]},
{name: "fix logging", files: ["pkg/log.go"]},
]
# No overlap → PARALLEL (all 3 at once)spawn_agent(message="Fix the null check in pkg/auth.go:validateToken around line 89...")
spawn_agent(message="Add timeout field to internal/config.go:Config struct...")
spawn_agent(message="Fix log rotation in pkg/log.go:rotateLogFile...")Bash(command='codex exec --full-auto -C "$(pwd)" -o .agents/codex-team/auth-fix.md "Fix the null check in pkg/auth.go:validateToken around line 89..."', run_in_background=true)
Bash(command='codex exec --full-auto -C "$(pwd)" -o .agents/codex-team/config-fix.md "Add timeout field to internal/config.go:Config struct..."', run_in_background=true)
Bash(command='codex exec --full-auto -C "$(pwd)" -o .agents/codex-team/logging-fix.md "Fix log rotation in pkg/log.go:rotateLogFile..."', run_in_background=true)spawn_agent(message="Fix these 3 issues in cmd/zeus.go: (1) rename spec_path to spec_location in QUEST_REQUEST payload (2) remove beads field (3) fix dispatch counter increment location")
# CLI equivalent:
Bash(command='codex exec --full-auto -C "$(pwd)" -o .agents/codex-team/zeus-fixes.md \
"Fix these 3 issues in cmd/zeus.go: \
(1) Line 245: rename spec_path to spec_location in QUEST_REQUEST payload \
(2) Line 250: remove the spurious beads field from the payload \
(3) Line 196: fix dispatch counter — increment inside the loop, not outside"', run_in_background=true)# Wave 1: non-overlapping tasks (sub-agent backend)
spawn_agent(message='Fix null check in pkg/auth.go:89...')
spawn_agent(message='Add timeout to internal/config.go...')
# Wait for Wave 1 (sub-agent backend)
wait(ids=["<id-1>", "<id-2>"], timeout_ms=120000)
# Wave 1: non-overlapping tasks (CLI backend)
Bash(command='codex exec ... -o .agents/codex-team/auth-fix.md "Fix null check in pkg/auth.go:89..."', run_in_background=true)
Bash(command='codex exec ... -o .agents/codex-team/config-fix.md "Add timeout to internal/config.go..."', run_in_background=true)
# Wait for Wave 1
TaskOutput(task_id="<id-1>", block=true, timeout=120000)
TaskOutput(task_id="<id-2>", block=true, timeout=120000)
# Read Wave 1 results — understand what changed
Read(.agents/codex-team/auth-fix.md)
git diff pkg/auth.go
# Wave 2: task that shares files with Wave 1 (sub-agent backend)
spawn_agent(message='Add rate limiting to pkg/auth.go and pkg/middleware.go. Note: validateToken now has a null check at line 89. Build on current file state.')
# Wave 2: CLI backend equivalent
Bash(command='codex exec ... -o .agents/codex-team/rate-limit.md \
"Add rate limiting to pkg/auth.go and pkg/middleware.go. \
Note: pkg/auth.go was recently modified — the validateToken function now has a null check at line 89. \
Build on the current state of the file."', run_in_background=true)
TaskOutput(task_id="<id-3>", block=true, timeout=120000)# Sub-agent backend:
wait(ids=["<id-1>", "<id-2>", "<id-3>"], timeout_ms=120000)
# CLI backend:
TaskOutput(task_id="<id-1>", block=true, timeout=120000)
TaskOutput(task_id="<id-2>", block=true, timeout=120000)
TaskOutput(task_id="<id-3>", block=true, timeout=120000)mkdir -p .agents/codex-team# GOOD: Specific file, line, exact change
"Fix in cmd/zeus.go line 245: rename spec_path to spec_location in the QUEST_REQUEST payload struct"
# BAD: Vague, requires exploration
"Fix the spec path issue somewhere in the codebase"Skill(skill="swarm")