codex-crew

Codex CLI as a first-class Claude Code subagent: task delegation, code review, second opinion. Inherits the user's ~/.codex/config.toml (no sandboxes, no restrictions), sessions are resumable, hangs are detected by a deterministic watchdog.

Contents

• agents/codex.md — transport subagent (sonnet). Holds the codex session: follow-ups via SendMessage continue the same dialogue. The task must include cwd:; optional codex options: (model/sandbox/effort) and review scope:.
• skills/codex-agent — delegate execution.
• skills/codex-review — review a branch/commit/uncommitted/files.
• skills/codex-consult — second opinion on a spec/plan, iterate to consensus.
• scripts/codex-run.sh — wrapper around codex exec --json with a watchdog (CODEX_STALL_TIMEOUT, default 600s of output stagnation → kill; the session continues via resume). Tests: tests/test-run.sh.

How it works

The orchestrator spawns the codex subagent with a task. The subagent writes a prompt file (transport preamble + task), launches codex-run.sh in the background, and polls the status file.

Review mode: the codex CLI can't combine a scope flag (--base/--commit/--uncommitted) with a custom prompt, so with a non-empty prompt file the script translates the scope into prompt text automatically; with no prompt file the native codex exec review <scope> path is used.

Prompt convention: wrapper instructions outside, the codex task between === TASK FOR CODEX === / === END TASK === markers — the wrapper forwards only the marked block, so it never mistakes the task for its own job, and wrapper instructions never leak into the codex prompt.

Install

claude plugin marketplace add <path-or-github-url>
claude plugin install codex-crew@codex-crew

Requires codex CLI ≥0.142.

Update after push (Claude Code doesn't re-fetch the cache; plugin update compares the version from plugin.json — no version bump, no content update):

# 1. bump version in .claude-plugin/plugin.json, commit, push
claude plugin marketplace update codex-crew
claude plugin update codex-crew@codex-crew

then /reload-plugins or restart the session (agent/skill definitions are snapshotted on reload; hot-patching the cache doesn't work).