The golden rule: Codex's self-report is a claim, not the truth. Always
capture its output, then independently verify the artifacts yourself (read the
files, re-run the tests) before treating the task as done.
Verified available on this machine: codex-cli 0.137.0, logged in via ChatGPT
(no API key needed). Confirm with codex login status.
codex exec \
--cd <workdir> \
--sandbox <read-only|workspace-write|danger-full-access> \
-o /tmp/codex_<rand>.txt \
"your metaprompt here" 2>>/tmp/codex_<rand>.log
- Prompt as the final arg, OR pipe via stdin:
echo "$PROMPT" | codex exec -
(good for long/generated prompts). If both are given, stdin is appended.
-o, --output-last-message <file> — writes ONLY Codex's final message to a
file. This is your clean capture; read it back, don't scrape the TUI stream.2>>/tmp/...log — Codex streams progress/reasoning to stderr; the final
message goes to stdout. Redirect stderr to a log so it doesn't bloat your
context. Generate the suffix with openssl rand -hex 4.--cd <dir> — Codex's working root. Scope it to the relevant subdir
(e.g. apps/api), not the whole monorepo, so it stays focused.--skip-git-repo-check — only needed when running outside a git repo.
read-only (default) — Codex can read/grep/run read-only commands but cannot
edit files or hit the network. Use for review, analysis, planning, "find the
bug", second opinions.workspace-write — can edit files in --cd (and --add-dir paths) and run
commands, but no network by default. Use for real implementation/refactors.danger-full-access — no sandbox at all. Avoid; only for throwaway/ephemeral
dirs you fully control.
Approvals: in exec mode Codex does not prompt for approvals. For a fully
autonomous run with no gating at all, add
--dangerously-bypass-approvals-and-sandbox. This is powerful — only use it when
the user has explicitly authorized autonomous edits AND the --cd is scoped, or
when running in an already-sandboxed/throwaway dir. When unsure, ask the user
which sandbox tier before running with write access.
codex exec resume --last "now also update the tests" # most recent session
codex exec resume <session-id> "..." # a specific one
The session id is printed at the start of each exec run. Use resume for
multi-turn delegation (draft → refine → fix) instead of re-sending all context.
- Delegate —
codex exec ... -o <out> 2>><log>.
- Capture — read
<out> (and <log>/--json if you need detail).
- Verify INDEPENDENTLY — do not trust Codex's "tests pass" / "done":
git status / git diff to see what actually changed.- Read the changed files yourself.
- Re-run the build/tests/linter yourself and read the real output.
- Iterate — if wrong,
codex exec resume --last "<correction>" and repeat.
- Report — tell the user what changed, what you verified, and how. State
plainly when something failed or was skipped.
Cleanup: remove /tmp/codex_* capture/log files (and any throwaway worktrees)
when done.
1---2name: codex-cli3description: Drive OpenAI's Codex CLI (`codex exec`) as a non-interactive coding sub-agent from inside Claude Code. Load WHENEVER you want to delegate a coding/analysis/refactor task to Codex, get a second opinion / adversarial review from another model, fan out parallel agents across files or worktrees, or run a long mechanical job while you stay the planner. Covers the exact `codex exec` flags, sandbox tiers, output capture, JSON/schema modes, session resume, parallel fan-out, and the mandatory "delegate → capture → independently verify, never trust the self-report" supervision loop.4---56<skill name="codex-cli">78<overview>9Codex CLI is OpenAI's terminal coding agent (Rust). Its **non-interactive** mode,10`codex exec`, makes it a perfect disposable sub-agent: you write the metaprompt,11Codex explores/edits/runs commands on its own, and returns a final message you12capture and verify. You stay the long-context planner; Codex is the implementer.1314The golden rule: **Codex's self-report is a claim, not the truth.** Always15capture its output, then independently verify the artifacts yourself (read the16files, re-run the tests) before treating the task as done.1718Verified available on this machine: `codex-cli 0.137.0`, logged in via ChatGPT19(no API key needed). Confirm with `codex login status`.20</overview>2122<the-core-command>23The one shape you'll use most:2425```bash26codex exec \27 --cd <workdir> \28 --sandbox <read-only|workspace-write|danger-full-access> \29 -o /tmp/codex_<rand>.txt \30 "your metaprompt here" 2>>/tmp/codex_<rand>.log31```3233- Prompt as the final arg, OR pipe via stdin: `echo "$PROMPT" | codex exec -`34 (good for long/generated prompts). If both are given, stdin is appended.35- `-o, --output-last-message <file>` — writes ONLY Codex's final message to a36 file. This is your clean capture; read it back, don't scrape the TUI stream.37- `2>>/tmp/...log` — Codex streams progress/reasoning to **stderr**; the final38 message goes to **stdout**. Redirect stderr to a log so it doesn't bloat your39 context. Generate the suffix with `openssl rand -hex 4`.40- `--cd <dir>` — Codex's working root. Scope it to the relevant subdir41 (e.g. `apps/api`), not the whole monorepo, so it stays focused.42- `--skip-git-repo-check` — only needed when running outside a git repo.43</the-core-command>4445<sandbox-tiers>46Pick the **least** privilege that lets the task succeed:4748- `read-only` (default) — Codex can read/grep/run read-only commands but cannot49 edit files or hit the network. Use for review, analysis, planning, "find the50 bug", second opinions.51- `workspace-write` — can edit files in `--cd` (and `--add-dir` paths) and run52 commands, but no network by default. Use for real implementation/refactors.53- `danger-full-access` — no sandbox at all. Avoid; only for throwaway/ephemeral54 dirs you fully control.5556Approvals: in `exec` mode Codex does not prompt for approvals. For a fully57autonomous run with no gating at all, add58`--dangerously-bypass-approvals-and-sandbox`. This is powerful — only use it when59the user has explicitly authorized autonomous edits AND the `--cd` is scoped, or60when running in an already-sandboxed/throwaway dir. When unsure, ask the user61which sandbox tier before running with write access.62</sandbox-tiers>6364<output-modes>65- Default: human-readable, final message on stdout (+ capture with `-o`).66- `--json` — newline-delimited JSON events on stdout (tool calls, file changes,67 messages). Use when you want to parse what Codex actually did, not just its68 prose summary.69- `--output-schema <file.json>` — force Codex's final response to conform to a70 JSON Schema. Use for reliable structured hand-back (e.g. a list of findings).71- `-m, --model <model>` — pin the model. `-i, --image <file>` — attach images.72 `--add-dir <dir>` — extra writable roots. `--ephemeral` — don't persist the73 session to disk.74</output-modes>7576<session-resume>77Codex sessions are stateful. To continue a prior run with its context intact:7879```bash80codex exec resume --last "now also update the tests" # most recent session81codex exec resume <session-id> "..." # a specific one82```8384The session id is printed at the start of each `exec` run. Use resume for85multi-turn delegation (draft → refine → fix) instead of re-sending all context.86</session-resume>8788<delegation-patterns>89- **One-shot task** — scope `--cd`, `workspace-write`, `-o` capture, verify.90- **Second opinion / adversarial review** — `read-only`, ask Codex to find bugs91 or critique your diff. Different model, different blind spots.92- **Plan/implement split** — you write the spec, Codex implements it, you review.93- **Refactor + test split** — Codex does the mechanical edit; you write/verify94 the tests (or vice-versa). Cross-checking catches more.95- **Parallel fan-out** — for N independent files/tasks, launch N `codex exec`96 runs, each with its own `-o`/log file. To avoid edit collisions when multiple97 WRITE runs touch the repo at once, give each its own git worktree98 (`git worktree add`) and point `--cd` there.99- **Cost routing** — small mechanical fixes → Codex (ChatGPT quota); deep100 long-context work → keep it yourself.101</delegation-patterns>102103<the-supervision-loop>104Never skip this. After every delegated run:1051061. **Delegate** — `codex exec ... -o <out> 2>><log>`.1072. **Capture** — read `<out>` (and `<log>`/`--json` if you need detail).1083. **Verify INDEPENDENTLY** — do not trust Codex's "tests pass" / "done":109 - `git status` / `git diff` to see what actually changed.110 - Read the changed files yourself.111 - Re-run the build/tests/linter yourself and read the real output.1124. **Iterate** — if wrong, `codex exec resume --last "<correction>"` and repeat.1135. **Report** — tell the user what changed, what you verified, and how. State114 plainly when something failed or was skipped.115116Cleanup: remove `/tmp/codex_*` capture/log files (and any throwaway worktrees)117when done.118</the-supervision-loop>119120<repo-specifics>121In this repo, respect the existing skills: prefer the `worktree` skill122(`pnpm worktree`) for isolated parallel Codex runs, and the `testing` and123`migration` skills' rules still apply to anything Codex produces — verify against124them. A Codex run is not a license to bypass repo conventions; you own the result.125</repo-specifics>126127</skill>
kortix-ai