codex-cli

<skill name="codex-cli">

<overview> Codex CLI is OpenAI's terminal coding agent (Rust). Its non-interactive mode, codex exec, makes it a perfect disposable sub-agent: you write the metaprompt, Codex explores/edits/runs commands on its own, and returns a final message you capture and verify. You stay the long-context planner; Codex is the implementer.

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. </overview>

<the-core-command> The one shape you'll use most:

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.

</the-core-command>

<sandbox-tiers> Pick the least privilege that lets the task succeed:

• 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. </sandbox-tiers>

<output-modes>

• Default: human-readable, final message on stdout (+ capture with -o).
• --json — newline-delimited JSON events on stdout (tool calls, file changes,

messages). Use when you want to parse what Codex actually did, not just its prose summary.

• --output-schema <file.json> — force Codex's final response to conform to a

JSON Schema. Use for reliable structured hand-back (e.g. a list of findings).

• -m, --model <model> — pin the model. -i, --image <file> — attach images.

--add-dir <dir> — extra writable roots. --ephemeral — don't persist the session to disk. </output-modes>

<session-resume> Codex sessions are stateful. To continue a prior run with its context intact:

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. </session-resume>

<delegation-patterns>

• One-shot task — scope --cd, workspace-write, -o capture, verify.
• Second opinion / adversarial review — read-only, ask Codex to find bugs

or critique your diff. Different model, different blind spots.

• Plan/implement split — you write the spec, Codex implements it, you review.
• Refactor + test split — Codex does the mechanical edit; you write/verify

the tests (or vice-versa). Cross-checking catches more.

• Parallel fan-out — for N independent files/tasks, launch N codex exec

runs, each with its own -o/log file. To avoid edit collisions when multiple WRITE runs touch the repo at once, give each its own git worktree (git worktree add) and point --cd there.

• Cost routing — small mechanical fixes → Codex (ChatGPT quota); deep

long-context work → keep it yourself. </delegation-patterns>

<the-supervision-loop> Never skip this. After every delegated run:

1. Delegate — codex exec ... -o <out> 2>><log>.
2. Capture — read <out> (and <log>/--json if you need detail).
3. 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.

1. Iterate — if wrong, codex exec resume --last "<correction>" and repeat.
2. 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. </the-supervision-loop>

<repo-specifics> In this repo, respect the existing skills: prefer the worktree skill (pnpm worktree) for isolated parallel Codex runs, and the testing and migration skills' rules still apply to anything Codex produces — verify against them. A Codex run is not a license to bypass repo conventions; you own the result. </repo-specifics>

</skill>