Skip to content
codex-team logo

Codex Team

codex-team

Use when you have 2+ tasks that Codex agents should execute. Runtime-native: Codex sub-agents when available, Codex CLI fallback otherwise. Handles file conflicts via merge/wave strategies. Triggers: "codex team", "spawn codex", "codex agents", "use codex for", "codex fix".

NeverSight/skills_feed1installs215stars

SKILL.md

Full skill instructions

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.

When to Use

  • You have 2+ tasks (bug fixes, implementations, refactors)
  • Tasks are well-scoped with clear instructions
  • You want Codex execution with predictable isolation
  • You may be in Claude or Codex runtime (skill auto-selects backend)

Don't use when: Tasks need tight shared-state coordination. Use /​swarm for dependency-heavy wave orchestration.

Backend Selection (MANDATORY)

Select backend in this order:

  1. spawn_agent available -> Codex experimental sub-agents (preferred)
  2. Otherwise -> Codex CLI via Bash (codex exec ...)

If neither is available, fall back to /​swarm.

Pre-Flight (CLI backend only)

# REQUIRED before spawning with Codex CLI backend
if ! which codex > /​dev/​null 2>&1; then
  echo "Codex CLI not found. Install: npm i -g @openai/​codex"
  # Fallback: use /​swarm
fi

# Model availability test
CODEX_MODEL="${CODEX_MODEL:-gpt-5.3-codex}"
if ! codex exec --full-auto -m "$CODEX_MODEL" -C "$(pwd)" "echo ok" > /​dev/​null 2>&1; then
  echo "Codex model $CODEX_MODEL unavailable. Falling back to /​swarm."
fi

Canonical Command

codex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o <output-file> "<prompt>"

Flag order: --full-auto -> -m -> -C -> -o -> prompt. Always this order.

Valid flags: --full-auto, -m, -C, -o, --json, --output-schema, --add-dir, -s

DO NOT USE: -q, --quiet (don't exist)

Cross-Project Tasks

When tasks span multiple repos/​directories, use --add-dir to grant access:

codex exec --full-auto -m gpt-5.3-codex -C "$(pwd)" --add-dir /​path/​to/​other/​repo -o output.md "prompt"

The --add-dir flag is repeatable for multiple additional directories.

Progress Monitoring (optional)

Add --json to stream JSONL events to stdout for real-time monitoring:

codex exec --full-auto --json -m gpt-5.3-codex -C "$(pwd)" -o output.md "prompt" 2>/​dev/​null

Key events:

  • turn.started / turn.completed — track progress
  • turn.completed includes token usage field
  • No events for 60s → agent likely stuck

Sandbox Levels

Use -s to control the sandbox:

LevelFlagUse When
Read-only-s read-onlyJudges, reviewers (no file writes needed)
Workspace write-s workspace-writeDefault with --full-auto
Full access-s danger-full-accessOnly in externally sandboxed environments

For code review and analysis tasks, prefer -s read-only over --full-auto.

Execution

Step 1: Define Tasks

Break work into focused tasks. Each task = one Codex agent (unless merged).

Step 2: Analyze File Targets (REQUIRED)

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 OverlapStrategyAction
All tasks touch same fileMergeCombine into 1 agent with all fixes
Some tasks share filesMulti-waveShared-file tasks go sequential across waves
No overlapParallelSpawn all agents at once
# 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 agent
tasks = [
  {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 1
tasks = [
  {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)

Step 3: Spawn Agents

Strategy: Parallel (no file overlap)

Codex sub-agent backend (preferred):

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...")

Codex CLI backend:

Bash(command='codex exec --full-auto -m "gpt-5.3-codex" -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 -m "gpt-5.3-codex" -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 -m "gpt-5.3-codex" -C "$(pwd)" -o .agents/​codex-team/​logging-fix.md "Fix log rotation in pkg/​log.go:rotateLogFile..."', run_in_background=true)

Strategy: Merge (same file)

Combine all fixes into a single agent prompt:

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 -m "gpt-5.3-codex" -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)

One agent, one file, no conflicts possible.

Strategy: Multi-wave (partial overlap)

# 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)

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.

Step 4: Wait for Completion

# 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)

Step 5: Verify Results

  • Read output files from .agents/​codex-team/
  • Check git diff for changes made by each agent
  • Run tests if applicable
  • For multi-wave: verify Wave 2 agents built correctly on Wave 1 changes

Output Directory

mkdir -p .agents/​codex-team

Output files: .agents/​codex-team/<task-name>.md

Prompt Guidelines

Good Codex prompts are specific and self-contained:

# 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"

Include in each prompt:

  • Exact file path(s)
  • Line numbers or function names
  • What to change and why
  • Any constraints (don't touch other files, preserve API compatibility)

For multi-wave Wave 2+ prompts, also include:

  • What changed in prior waves (summarized, not raw diffs)
  • Current state of shared files after prior edits

Limits

  • Max agents: 6 per wave (resource-reasonable)
  • Timeout: 2 minutes default per agent. Increase with timeout param for larger tasks
  • Max waves: 3 recommended. If you need more, reconsider task decomposition

Fallback

If Codex is unavailable, use /​swarm with Claude-native Task tool agents:

Task(description="Fix task 1", subagent_type="general-purpose", run_in_background=true, prompt="...")

Quick Reference

ItemValue
Modelgpt-5.3-codex
Commandcodex exec --full-auto -m "gpt-5.3-codex" -C "$(pwd)" -o <file> "prompt"
Output dir.agents/​codex-team/
Max agents/​wave6 recommended
Timeout120s default
StrategiesParallel (no overlap), Merge (same file), Multi-wave (partial overlap)
Fallback/​swarm (runtime-native)

More skills from NeverSight

avnu logo
NeverSight/skills_feed

avnu

Integrate avnu SDK for Starknet DeFi: token swaps with best-price routing, DCA recurring buys, native staking, gasless transactions via paymaster, and market data. Use when building Starknet trading, DEX aggregation, or DeFi automation features.

215 0
View
post-to-x logo
NeverSight/skills_feed

post-to-x

发布内容和文章到 X (Twitter)。支持带图片的普通推文和 X Articles(长文)。使用真实的 Chrome 和 CDP 来绕过自动化检测。

215 0
View
ralph-prompt-builder logo
NeverSight/skills_feed

ralph-prompt-builder

Master orchestrator for generating Ralph Wiggum-compatible prompts. Analyzes task requirements and routes to appropriate generator (single-task, multi-task, project, or research). Use when you need to create any Ralph loop prompt and want automatic selection of the right generator.

215 0
View
branch-comparison logo
NeverSight/skills_feed

branch-comparison

Use when the user asks to compare branches, analyze git diffs, review changes between branches, update specifications based on code changes, or analyze what changed. Triggers on keywords like "compare branches", "git diff", "what changed", "branch comparison", "code changes", "spec update".

215 0
View
fastapi-development logo
NeverSight/skills_feed

fastapi-development

Build high-performance FastAPI applications with async routes, validation, dependency injection, security, and automatic API documentation. Use when developing modern Python APIs with async support, automatic OpenAPI documentation, and high performance requirements.

215 0
View
zendesk-chat logo
NeverSight/skills_feed

zendesk-chat

Enables Claude to manage Zendesk Chat conversations, support tickets, and customer service operations

215 0
View
forge logo
NeverSight/skills_feed

forge

Mine transcripts for knowledge - decisions, learnings, failures, patterns. Triggers: "forge insights", "mine transcripts", "extract knowledge".

215 0
View
mixpanel logo
NeverSight/skills_feed

mixpanel

Track product analytics and user behavior with Mixpanel's event-based platform.

215 0
View
ocpp logo
NeverSight/skills_feed

ocpp

OCPP protocol reference for EV charging infrastructure development. Covers OCPP 2.0.1 and OCPP 1.6J. Use when working with OCPP messages, charging station code, CSMS/Central System backends, smart charging, transaction handling, or EV charging protocols. Activates on keywords: OCPP, charging stat...

215 0
View
bee-collect logo
NeverSight/skills_feed

bee-collect

Gather scattered ideas into organized GitHub issues. The bee collects pollen from every flower, checks if the hive already has it, and carefully deposits new work in the comb for later. Never edits code—only organizes the work ahead. Use when creating issues from TODOs or planning work.

215 0
View
vercel-react-native-skills logo
NeverSight/skills_feed

vercel-react-native-skills

Comprehensive best practices for React Native and Expo applications. Contains rules across multiple categories covering performance, animations, UI patterns, and platform-specific optimizations.

215 0
View
agent-builder logo
NeverSight/skills_feed

agent-builder

Provides guidance for building and deploying Claude Agent SDK agents and Claude Code Skills. Use when designing agents (dev or non-dev), choosing architectures/tools, or deploying to a VPS.

215 0
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View