# codex-crew

Codex CLI as a first-class Claude Code subagent: delegate, review, consult. Respects your `~/.codex/config.toml`, sessions resumable, stall watchdog.

## Install

```
/plugin marketplace add smartass/codex-crew
/plugin install codex-crew@codex-crew
```

Requires `codex CLI >=0.151` and `jq`.

## How it works

Orchestrator → `codex` subagent (`agents/codex.md`) → `scripts/codex-run.sh` → `codex exec --json` (`--skip-git-repo-check -o last.md`). Non-empty `prompt.md` is fed via stdin `-` so flags and prompt combine. Stall watchdog (`CODEX_STALL_TIMEOUT`, default 600s of event silence → kill; resume via `thread_id`). `cwd:` in task is mandatory; `codex options:` forwarded verbatim. Review scope (`--base`/`--commit`/`--uncommitted`) is translated to prompt text when a custom prompt is present (CLI forbids scope + prompt together), otherwise native `codex exec review <scope>`.

## Skills

| Skill | Trigger |
|---|---|
| `codex-agent` | `delegate to codex`, `have codex do` — execution, bugfix, research |
| `codex-review` | `codex review` — branch (`--base`), commit, uncommitted, or files |
| `codex-consult` | `second opinion`, `have codex review the spec/plan` — iterate to consensus (max 5 rounds) |

Details: `skills/references/common.md`.

## Permissions & Sandbox

Default inherits `~/.codex/config.toml` (no flags injected). Override per-task via `codex options:`:

- `-s read-only | workspace-write | danger-full-access`
- `--add-dir <dir>` — extra writable directory
- `--dangerously-bypass-approvals-and-sandbox` — dangerous, only in an externally sandboxed environment

Example: `codex options: -s workspace-write --add-dir /tmp`

Flags are saved per-job and re-applied on `resume`.

## Models & Reasoning

Default from `~/.codex/config.toml` (`model`, `model_reasoning_effort`). Discovery:

```
./scripts/codex-models.sh
# or
codex debug models | jq '[.models[] | select(.visibility=="list") | {slug, levels: [.supported_reasoning_levels[].effort]}]'
```

Pass via `codex options: -m <model-from-discovery> -c model_reasoning_effort="<effort-from-discovery>"` (values from `scripts/codex-models.sh` output).

## Updating

Bump `version` in `.claude-plugin/plugin.json`, commit, push, then:

```
/plugin marketplace update codex-crew
/plugin update codex-crew@codex-crew
/reload-plugins
```

No version bump → no update (Claude Code caches by version).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome — keep changes minimal and EN-only.