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