codex-workers

A Claude Code user-level skill that makes the current Claude session the engineering lead while one or more OpenAI Codex CLI workers implement bounded slices in isolated git worktrees.

Claude keeps the judgment: repository reconnaissance, planning, lane decomposition, shared contracts, diff review, integration, and final verification. Codex workers only implement their assigned lane and run the checks in their brief.

Usage

/codex-workers <objective>

/codex-workers status [run-id]
/codex-workers resume [run-id]
/codex-workers cancel [run-id]
/codex-workers cleanup [run-id]

Example:

/codex-workers Add organization invitations, including the API, settings UI,
tests, and migration.

Claude plans, decides whether the work is one worker / parallel lanes / partly sequential (default max 3 concurrent lanes), writes one bounded brief per lane, launches codex exec workers concurrently in per-lane worktrees, reviews every diff itself, integrates accepted lanes in dependency order, and runs repo-wide checks.

Requirements

• Claude Code v2.1.196+ (uses ${CLAUDE_SKILL_DIR} substitution)
• codex CLI on PATH, authenticated (codex login status)
• Python 3.9+ as python3

Install

Clone into your user-level skills directory (or symlink a clone there):

git clone https://github.com/Moustafa93/codex-workers.git ~/.claude/skills/codex-workers

If you plan to modify or contribute to the skill, keep one canonical clone and symlink it into Claude Code. That prevents the installed copy and Git checkout from drifting apart:

git clone https://github.com/Moustafa93/codex-workers.git ~/projects/codex-workers
mkdir -p ~/.claude/skills
ln -s ~/projects/codex-workers ~/.claude/skills/codex-workers

After editing, commit and push from ~/projects/codex-workers; Claude Code sees the same files immediately through the symlink.

Layout

• SKILL.md — the lead protocol Claude follows.
• scripts/codex_workers.py — stdlib-only runner: prepare, launch, status, list, wait, report, kill, cleanup. Run state lives under <git-common-dir>/codex-workers/runs/<run-id>/; worktrees in a sibling directory <repo>-codex-workers/<run-id>/<lane> on branches codex-workers/<run-id>/<lane>.
• references/lane-brief.md — the per-lane brief template.
• references/review-checklist.md — the lane review protocol.

Safety properties

• One worktree and branch per lane; workers never share a worktree.
• The user's checkout is never reset, cleaned, or stashed; a dirty checkout blocks automatic integration.
• Workers run under Codex's workspace-write sandbox (network off by default), cannot write shared Git metadata, and are told not to push, merge, commit, or broaden scope.
• Cleanup refuses to remove worktrees containing tracked, untracked, or ignored files unless forced with explicit user direction; branches are always kept.
• All subprocesses use argument arrays; lane IDs are sanitized before use in paths and branch names.

Uninstall

rm -rf ~/.claude/skills/codex-workers

Per repository where it was used, optionally delete the leftover <repo>-codex-workers/ sibling directory, run git worktree prune, and delete unwanted codex-workers/* branches.

Development

The runner uses only Python's standard library. Run the fixture suite with:

python3 -m unittest discover -s tests -v

The process supervisor currently supports Linux and macOS. Native Windows is not supported because worker-group termination relies on POSIX process groups.