Codex Swarm

Codex Swarm

Overview

Run Codex CLI tasks inside cwd subdirectories only, using structured JSON input and optional parallel execution. Use this skill to orchestrate multiple Codex runs across sibling folders safely.

Quick Start

Run from the workspace root that should act as the boundary:

echo '{"jobs":[{"dir":"services/api","task":"Add health check endpoint."},{"dir":"services/worker","task":"Document retry policy."}],"max_parallel":2}' \
  | python3 scripts/codex_swarm.py

Input Schema

Provide JSON via stdin only.

{
  "jobs": [
    {"dir": "relative/path", "task": "..."}
  ],
  "max_parallel": 2
}

Rules:

• Require jobs as a non-empty array.
• Require each job to include dir and task as non-empty strings.
• Forbid current directory (.) and any .. segment.
• Forbid absolute paths or ~-prefixed paths.
• Require dir to exist and resolve inside the current working directory.
• Use max_parallel as an optional positive integer; default to min(4, len(jobs)).

Behavior

• Resolve each dir against pwd and reject paths outside.
• Run codex exec --model gpt-5.2-codex --full-auto --skip-git-repo-check "<task>" in each target directory.
• Execute jobs in parallel up to max_parallel.
• Log cwd, job count, each job's resolved dir, command, and exit code to stderr.

Scripts

• scripts/codex_swarm.py: JSON-only runner with safety checks and parallel execution.

Troubleshooting

• If Codex fails with a permissions error accessing ~/.codex/sessions, fix ownership and retry:
  • sudo chown -R $(whoami) /home/<your-user-name>/.codex/sessions
• If you can't or don't want to use sudo, alternatives:
  • Check current ownership/permissions: ls -ld /home/<your-user-name>/.codex /home/<your-user-name>/.codex/sessions
  • Verify your umask isn't too restrictive (e.g. umask 0022) before launching Codex again.
  • Recreate the sessions directory (only if it's safe for you to do so): mv /home/<your-user-name>/.codex/sessions /home/<your-user-name>/.codex/sessions.bak && mkdir -p /home/<your-user-name>/.codex/sessions