codex-agents · diff
git:20261107.53704ef to git:20261108.6aba512
89 added, 106 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: codex-agents
description: "'Ask Codex', 'check with Codex', handing Codex a build or review, or stuck between two framings: the Codex CLI as peer, builder or fresh reviewer."
---
# Codex agents — the Codex CLI as peer, builder and reviewer
- Codex is a peer, same standing as Claude. Not a formatter, not a gate, not an authority. It runs on the newest model the Codex CLI offers, at its highest reasoning effort (`xhigh`, the wrapper's default on every turn).
-
- **It can build, and what it builds is reviewed by someone else.** Hand it a build stage — the goal, the decisions that bind it, the files it will touch — and read the diff that comes back before believing it: a delegated diff is unreviewed code. The session that wrote code never clears it; an independent review (the `independent-review` skill, or whatever the project uses) does, and Codex can be that reviewer for code it didn't write (§ Reviewer). Deciding what the product should do, accepting or rejecting a review finding, anything that touches a real system, development included (any database, even one only you use, a server, a setting), and judging that a stage is done stay with the session agent; the brief says so, and asks for each real-system step as one command the session agent runs. Without the Codex CLI, or while it is out of usage (§ Resume or start fresh), the session agent builds the stage itself.
-
- **Delegate only what is worth the hand-off; the test is size, not time.** If the brief would be nearly as long as the diff, write the diff: a stage small enough to describe precisely is small enough to write, and handing it over only buys a wait. A build round that has made no writes on a small change (check `git status`) is stopped, its leftover process killed, and the change written in-session rather than waited on. What stays with the session agent is unchanged, and its diff still gets the independent review. (`2026-09-22`, a builder sat twelve minutes on a fifteen-line change with zero writes and a clean tree.)
-
- The way the human manages Claude (goal + context, not step-by-step; trust judgment; push back on disagreement) is how Claude manages Codex.
+ **Treat Codex as a peer with the same standing as Claude.** Not a formatter, not a gate, not an authority. Run it on the newest model the Codex CLI offers, at its highest reasoning effort: `xhigh`, the wrapper's default on every turn.
- Codex can write code AND generate images directly (multimodal output) — don't assume deliverables must be HTML/code. If the goal is a PNG, say that. Don't translate it to "an HTML file we'll screenshot."
+ **It can build, and what it builds is reviewed by someone else.** Hand it a build stage with the goal, binding decisions and files it will touch. Read its diff before believing it; a delegated diff is unreviewed code. The session that wrote code never clears it. An independent review does, through `independent-review` or whatever the project uses. Codex can review code it didn't write (§ Reviewer).
- ## Core discipline (read before every session)
+ **Keep product decisions, real systems and stage-completion judgement with the session agent.** This includes accepting or rejecting review findings and anything touching a real system, development included. Any database, even one only you use, a server and a setting count. Say so in the brief, asking for each real-system step as one command the session agent runs. Without the Codex CLI, or while it is out of usage (§ Resume or start fresh), the session agent builds the stage itself.
- 1. **Peer, not tool.** Same standing as Claude. Trust its judgment on path, structure, format, fonts, dimensions, libraries — Codex picks those. If it picks something you wouldn't have, that's a useful disagreement to surface, not a defect. Codex's view is **not binding** — push back where warranted.
+ **Delegate only what is worth the hand-off; the test is size, not time.** If the brief would be nearly as long as the diff, write the diff. A stage small enough to describe precisely is small enough to write, and handing it over only buys a wait. Stop a build round that has made no writes on a small change; check `git status`. Kill its leftover process and write the change in-session. The session agent keeps the same responsibilities, and its diff still gets independent review.
- 2. **Early, not late.** Bring Codex in at ideation and framing, not only as a pre-publish gate. The cheapest wins are at the start: choosing the angle, naming the load-bearing claim, deciding what to cut. Late peer-review is the *least* valuable use.
+ **Manage Codex with the goal, context and room for judgement.** Use the way the human manages Claude: avoid step-by-step direction, trust judgement and push back on disagreement.
- 3. **Strategic context, not step-by-step.** Hand over the goal, the facts, and the reasoning behind non-obvious choices. Do **not** prescribe paths, filenames, fonts, dimensions, libraries, chart types, or step-by-step procedures unless they are hard requirements.
+ **Ask for the deliverable's actual format, including an image when needed.** Codex can write code and generate images directly through multimodal output. If the goal is a PNG, say that. Don't translate it to "an HTML file we'll screenshot."
- 4. **Iterate.** ~3-8 turns is normal. **Stopping at turn 1 because Codex produced a draft is the failure mode** — that treats Codex like a one-shot generator. The value is in the back-and-forth.
+ ## Core discipline (read before every session)
- 5. **Converge before surfacing.** The human arbitrates intent and taste, not editorial trade-offs two agents can resolve. Default: converge first, present one result.
+ 1. **Treat Codex as a peer, not a tool.** It has the same standing as Claude. Trust its judgement on path, structure, format, fonts, dimensions and libraries. A choice you wouldn't have made is a useful disagreement to surface, not a defect. Its view is not binding; push back where warranted.
+ 2. **Bring Codex in at ideation and framing, before a sign-off.** The cheapest wins concern the angle, load-bearing claim and what to cut. Late peer review is the least valuable use; don't use it only as a pre-publish gate.
+ 3. **Give the goal, facts and reasoning behind non-obvious choices.** Do not prescribe paths, filenames, fonts, dimensions, libraries, chart types or step-by-step procedures unless they are hard requirements.
+ 4. **Iterate.** Continue iterating after Codex produces the first draft. About 3–8 turns is normal. Stopping at turn 1 treats Codex as a one-shot generator; the value comes from the back-and-forth.
+ 5. **Converge before surfacing.** The human arbitrates intent and taste, not editorial trade-offs two agents can resolve. Default to one result after convergence.
## When to invoke (proactively, not just on explicit request)
- Explicit invocation:
- - "check with Codex" / "iterate with Codex" / "ideate with Codex" / "ask Codex"
+ **Invoke Codex for explicit requests and decisions that need a peer.** Explicit requests include "check with Codex", "iterate with Codex", "ideate with Codex" and "ask Codex". Claude should also reach for this skill without being asked in these situations:
- Proactive invocation (Claude should reach for this skill without being asked):
- - Stuck between two reasonable framings/angles — would otherwise punt to the human
- - Pressure-testing a load-bearing claim, structure, or hook before committing
- - About to ask the human to choose between options two agents could argue through
- - Have a draft + an unvoiced critique you haven't worked through
- - Important deliverable where a fresh model's misses would matter (different model, different blind spots)
+ - **Consult Codex when stuck between two reasonable framings or angles.** Do this before punting the choice to the human.
+ - **Pressure-test a load-bearing claim, structure or hook before committing.**
+ - **Argue options through before asking the human to choose.** Use this when two agents could resolve the choice.
+ - **Work through an unvoiced critique of a draft with Codex.**
+ - **Use a fresh model when its misses would matter on an important deliverable.** A different model has different blind spots.
- Do **not** invoke for: routine drafting, formatting, mechanical tasks Claude can confidently handle in-session. This is a peer-agent skill, not a text-formatter API.
+ **Do not invoke Codex for routine work Claude confidently handles in-session.** This includes routine drafting, formatting and mechanical tasks. This is a peer-agent skill, not a text-formatter API.
## Opening turn — the four things Codex needs
+ **Give Codex the target, research, draft and specific uncertainty.**
+
| | What | Example |
|---|---|---|
- | **TARGET** | What we're producing or deciding | "X reply to <link>", "framing for <topic>", "call on <trade-off>" |
- | **RESEARCH** | What's actually known | Parent tweet, source quotes, verified facts, what the other party actually said, audience size, prior posts |
- | **DRAFT** | Current version + variants considered | Paste the artifact, not a description of it |
- | **REASONING** | Why you're stuck | What you've rejected and why; name the specific load-bearing question. Not "give me feedback" — name the genuine uncertainty |
+ | TARGET | What we're producing or deciding | "X reply to <link>", "framing for <topic>", "call on <trade-off>" |
+ | RESEARCH | What's actually known | Parent tweet, source quotes, verified facts, what the other party actually said, audience size, prior posts |
+ | DRAFT | Current version + variants considered | Paste the artifact, not a description of it |
+ | REASONING | Why you're stuck | What you've rejected and why; name the specific load-bearing question. Not "give me feedback" — name the genuine uncertainty |
- Long opening briefs go to a scratch file (system temp, project scratch dir, whatever the cwd convention is), then `--read`:
+ **Put long opening briefs in a scratch file and use `--read`.** Use system temp, project scratch or whatever the working directory's convention is.
```bash
python <skill dir>/scripts/codex.py --new --read <scratch_file>
```
- Add `--sandbox workspace-write` if Codex needs to write files or pull data, and `--cwd <repo>` to scope the session to the repository it works in.
-
- **Pass it on every build dispatch, not only the ones you think are new sessions.**
- The default is `read-only`, and the flag applies to new sessions only, so a resume you
- expected and did not get silently lands read-only. What comes back then is a *reasoned
- report* that changed nothing — it argues a verdict, notes real defects, and reads
- exactly like a round that worked, because nothing failed. The tell is the disk: check
- `git status` and file mtimes before believing a build round happened at all.
- (`2026-09-16`: a round meant to fix twelve failing tests resumed as a
- new session, ran read-only, and reported a decision with no diff behind it.)
+ **Pass it on every build dispatch, not only the ones you think are new sessions.** Add `--sandbox workspace-write` when Codex needs to write files or pull data. Add `--cwd <repo>` to scope the session to its repository. The sandbox defaults to `read-only`, and its flag applies only to new sessions. An expected resume that starts new silently lands read-only. The resulting reasoned report argues a verdict and notes real defects while changing nothing, with nothing failing. It reads exactly like a round that worked. Check `git status` and file mtimes before believing a build round happened.
- **Even with `workspace-write`, a build cannot commit, and cannot run git in another
- checkout.** The sandbox keeps `.git` read-only, so `git add` fails creating
- `.git/index.lock` (Permission denied); in a linked worktree the index lives in the main
- checkout's `.git/worktrees/<name>/`, which fails the same way. Adding that `.git` with
- `--add-dir` did not lift it. On Windows the sandbox also runs commands as a separate local
- user, so git refuses any other repository as "dubious ownership". (Codex CLI 0.159 on
- Windows 11, `2026-10-25`, all three reproduced in scratch repositories; `2026-10-23`, a
- monitoring product: four worktree builds came back uncommitted, three of them quoting the
- `index.lock` error; other platforms not tested here.) So the brief asks for the work left
- uncommitted, with its commit message in the handoff, and you read the diff and commit it.
- A brief that sends it to another repository for prior art says to read the files from disk.
+ **Leave sandboxed builds uncommitted and ask for a commit-message handoff.** On Codex CLI 0.159, Windows 11, `workspace-write` could neither commit nor run git in another checkout (observed 2026-10-25). All three restrictions below were reproduced in scratch repositories. Other platforms were not tested here. The sandbox keeps `.git` read-only: `git add` fails creating `.git/index.lock` with `Permission denied`. A linked worktree's index lives in the main checkout's `.git/worktrees/<name>/` and fails the same way. Adding that `.git` with `--add-dir` did not lift the restriction. Windows also runs sandbox commands as a separate local user, so git refuses other repositories as "dubious ownership". Read the diff and commit it yourself. If a brief sends Codex to another repository for prior art, tell it to read files from disk.
- **A build that adds or changes screens names the `ui-design` skill, `$app-stack:ui-design`,** and carries its rows of the jobs map. Codex loads a skill only from a pack installed in Codex, so before the first such brief, `codex plugin list` shows `app-stack@product-engineering` installed and enabled; if it doesn't, install it (`codex plugin marketplace add phuryn/product-engineering`, then `codex plugin add app-stack@product-engineering`). (`2026-11-03`, an evals product: Codex, with no pack installed, built screens without the method, and the owner's click-through found five layout bugs. Once the pack was installed, a headless `codex exec` loaded `$app-stack:ui-design`, codex-cli 0.166.0.)
+ **Name `$app-stack:ui-design` in a build that adds or changes screens.** Name the `ui-design` skill with that invocation and carry its jobs-map rows in the brief. Codex loads a skill only from a pack installed in Codex. Before the first such brief, run `codex plugin list` and check `app-stack@product-engineering` is installed and enabled. If absent, run `codex plugin marketplace add phuryn/product-engineering`, then `codex plugin add app-stack@product-engineering`. Loading `$app-stack:ui-design` in a headless `codex exec` was observed on codex-cli 0.166.0, 2026-11-03.
- **A build brief budgets integration tests against the real database**, including the session agent's integration-fix pass when the sandbox cannot run them: apply the `test-harness` skill's round-trip budget (§ Tests and docs are part of the change). State the target's measured latency and which checks the session agent runs.
+ **Budget real-database integration tests in the build brief.** Include the session agent's integration-fix pass when the sandbox cannot run them. Apply `test-harness`'s round-trip budget (§ Tests and docs are part of the change). State the target's measured latency and which checks the session agent runs.
## Follow-up turns — conversational, short, peer-to-peer
- React like a colleague. Agree where it's right, push back where it's wrong, ask why where it's surprising, name what you notice it missed. Don't re-package the goal as a new structured prompt. Don't number your points.
+ **React like a colleague without rewriting the goal or numbering points.** Agree where it's right, push back where it's wrong, ask why where it's surprising, and name what it missed. Don't re-package the goal as a new structured prompt.
> "the opener still feels abstract — what if we lead with X instead?"
> "agree on the third option, but 'harness' is too broad, doesn't it collapse the distinction you just made?"
> "you're right about Y but it loses Z — can we keep both?"
```bash
python <skill dir>/scripts/codex.py "<your reaction>"
```
- Auto-resumes the session the wrapper last ran in this directory. Loop until convergence or until the disagreement is articulated cleanly enough to hand back to the human.
+ The wrapper auto-resumes the session it last ran in this directory. Loop until convergence or until the disagreement is clear enough to hand back to the human.
## Iterate — signs you should still be going
- - You have a critique of the current draft you haven't voiced yet
- - Codex made a choice you don't fully buy but didn't push on
- - There's a non-obvious option neither of you has explored
- - The human's stated goal isn't fully reflected in the draft yet
- - You're tempted to ask the human "which version do you prefer" between two reasonable options — that's a question for Codex first
- - You've identified an open trade-off (recipe vs frame, tighter vs richer, hook A vs B) and haven't run it past Codex yet
+ **Keep iterating while relevant critiques, choices or trade-offs remain untested.**
+ - A critique of the current draft you haven't voiced.
+ - A choice Codex made that you don't fully buy and haven't pushed on.
+ - A non-obvious option neither of you has explored.
+ - The human's stated goal not fully reflected in the draft.
+ - The temptation to ask the human which of two reasonable versions they prefer. Ask Codex first.
+ - An open trade-off you haven't run past Codex: recipe versus frame, tighter versus richer, or hook A versus B.
+
## Iterate — signs you've actually converged
- - You'd defend the current draft against your own critique
- - Codex and you have stopped finding new angles
- - Remaining trade-offs are taste, not correctness
+ **Stop iterating when the draft holds and only taste remains.** You would defend it against your own critique. Neither you nor Codex finds new angles, and remaining trade-offs concern taste rather than correctness.
## Surface to the human — when
- - **Genuine deadlock** — both agents iterated through it and stayed disagreed; the disagreement is articulated cleanly
- - **Intent ambiguity** — what the human wants is unclear, and resolving it would change the iteration direction
- - **Hard new info** — a constraint, audience signal, content rule, or strategic call the human knows and you don't, that would reshape the draft
+ **Surface deadlock, unclear intent or consequential information you lack.**
- Do **not** surface:
- - "Which of these two do you prefer" between two reasonable options not argued through with Codex
- - Taste-level word choice / hook / closer trade-offs not pressure-tested
- - Spotted trade-offs (tighter vs richer, frame vs recipe) you haven't run past Codex
+ - **State genuine deadlock after both agents iterated and still disagree.** Articulate the disagreement cleanly.
+ - **Ask about unclear intent when resolving it changes the iteration's direction.**
+ - **Surface information the human knows and you don't when it would reshape the draft.** This includes a constraint, audience signal, content rule or strategic call.
- **The failure mode: stopping at 1-2 Codex turns and dumping the open calls on the human as a menu.** The loop is supposed to converge before the human sees the result.
+ **Do not surface reasonable options or taste trade-offs you haven't argued through.** This includes "which of these two do you prefer", untested word choice, hook or closer choices, and tighter-versus-richer or frame-versus-recipe trade-offs. Stopping after 1–2 Codex turns and dumping open calls on the human as a menu is the failure mode. Converge before the human sees the result.
## Anti-patterns
- - Numbered "concrete asks" with sub-bullets in the brief — that's recipe-writing dressed up as a brief, not partnership. State the goal once, hand over context, let the partner pick the means.
- - Prescribed file paths, filenames, fonts, dimensions, libraries, frameworks (unless they're hard constraints — "the existing system uses X" is context, not a directive).
- - On follow-up turns: a fresh structured prompt. If you're rewriting the goal section in turn 3, you've left the conversation.
- - Treating Codex's view as binding. It isn't.
- - Translating a deliverable to a different format because you assume Codex can only produce code/HTML. It can produce images directly.
+ - **State the goal once and let the partner pick the means.** Numbered "concrete asks" with sub-bullets dress a step-by-step recipe as a brief.
+ - **Prescribe paths and other implementation choices only when they are hard constraints.** This includes file paths, filenames, fonts, dimensions, libraries and frameworks. "The existing system uses X" gives context rather than a directive.
+ - **Keep follow-up turns conversational instead of sending a fresh structured prompt.** Rewriting the goal section in turn 3 leaves the conversation.
+ - **Treat Codex's view as a judgement you can challenge.** It isn't binding.
+ - **Keep the requested deliverable format when Codex can produce it directly.** Don't translate it because you assume Codex produces only code or HTML; it can generate images.
## Resume or start fresh
- A build round either continues a session or starts one; the wrapper continues by default, so starting fresh is the choice you make on purpose.
+ **Continue by default and choose fresh sessions deliberately.** A build round either continues a session or starts one.
- - **Within a stage, resume.** Follow-up rounds on the same piece of work — fixing what a review found, finishing it — continue the session that built it. The wrapper resumes per directory, so in the stage's worktree this is the default.
- - **A new stage or a new area starts fresh, with `--new`.** What the project knows belongs in its docs and the stage's brief, not in an old thread. A long thread carries assumptions the docs have since replaced and fills its context window, while a fresh session's start-up is a few minutes of reading. If a fresh session would miss something, that is a gap in the docs: write it there.
- - **Parallel builds get a worktree, a session and a marker each.** One session can't drive two builds. The wrapper's marker is one file per user and holds one directory, so a second build's run overwrites the first's, and the first build's next round starts a new session (read-only unless `--sandbox` is passed) instead of resuming. Give each build its own marker: `CODEX_AGENTS_STATE=<a file per build>` on every call for it.
- - **An earlier session can still be resumed, by its id: `--session <id>`.** Every session stays in `~/.codex/sessions/<yyyy>/<mm>/<dd>/`, one `rollout-<time>-<id>.jsonl` each, whose first line names its `cwd`; the wrapper also prints each run's id. Run it with the `--cwd` that session ran in, and with `--model` when it ran on anything but the config default, since a resume does not keep the model (§ Session continuity). It fails rather than starting a new session; once codex has opened it, even on a run that then fails, the marker names it, so the next plain call continues it.
- - **A usage limit makes the builder unavailable, as a missing CLI does.** Codex answers "You've hit your usage limit … try again at <time>" and exits at once. Wait when the reset is near; otherwise the session agent builds the stage itself, and the independent review still applies. The marker keeps the stage's session through the failure, so after the reset the next call continues it. (`2026-10-22`: the reset was 90 minutes away, and the session agent built two stages with its own subagents rather than wait.)
+ - **Within a stage, resume.** Follow-up rounds fixing review findings or finishing the same work continue the session that built it. The wrapper resumes per directory, so this is the default in the stage's worktree.
+ - **A new stage or a new area starts fresh, with `--new`.** Project knowledge belongs in docs and the stage's brief, not an old thread. Long threads carry replaced assumptions and fill their context window; a fresh start takes a few minutes of reading. If a fresh session would miss something, write it in the docs.
+ - **Parallel builds get a worktree, a session and a marker each.** One session can't drive two builds. The wrapper's marker is one file per user and holds one directory, so the second build overwrites the first's marker. The first build's next round then starts new, read-only unless `--sandbox` is passed. Use `CODEX_AGENTS_STATE=<a file per build>` on every call for each build.
+ - **An earlier session can still be resumed, by its id: `--session <id>`.** Sessions stay in `~/.codex/sessions/<yyyy>/<mm>/<dd>/`, one `rollout-<time>-<id>.jsonl` each. Its first line names `cwd`, and the wrapper prints each run's id. Use that session's `--cwd`, plus `--model` if it used something other than the config default; resume doesn't keep the model (§ Session continuity). Explicit resume fails rather than starting new. Once Codex opens it, even if the run later fails, the marker names it and the next plain call continues it.
+ - **A usage limit makes the builder unavailable, as a missing CLI does.** Codex answers "You've hit your usage limit … try again at <time>" and exits at once. Wait when reset is near; otherwise the session agent builds the stage itself, and independent review still applies. The marker keeps the stage's session through failure, so the next call after reset continues it.
## Reviewer
- A review round's discipline (what it covers, the brief, triage, when to stop) is the `independent-review` skill's, and its wrapper runs Grok or a fresh Claude Code session by default. Codex reviews a round when the repository's instructions name it or the owner asks. Get the round's prompt from that skill (its wrapper's `--subject-only` writes the subject and the prompt into the git directory and prints their paths), then run it in a new session that meets the review bar, never this wrapper and never a resume of the thread that built the code:
+ **Apply `independent-review` for round scope, brief, triage and stopping.** Its wrapper defaults to Grok or a fresh Claude Code session. Codex reviews when repository instructions name it or the owner asks. Get that skill's prompt with its wrapper's `--subject-only`, which writes subject and prompt into the git directory and prints their paths. Use a new session meeting the review bar, never this wrapper and never a resume of the building thread:
```bash
# macOS and Linux
codex exec --ephemeral --ignore-user-config --ignore-rules -s read-only \
-m <the newest model> -c model_reasoning_effort=xhigh -C <repo> - < "<prompt file>" > "$S/review-NNN.md" 2> "$S/review-NNN.err"
# Windows: the same, plus the sandbox mode under [windows] in ~/.codex/config.toml (elevated or unelevated)
codex exec --ephemeral --ignore-user-config --ignore-rules -s read-only -c 'windows.sandbox="<that mode>"' \
-m <the newest model> -c model_reasoning_effort=xhigh -C <repo> - < "<prompt file>" > "$S/review-NNN.md" 2> "$S/review-NNN.err"
```
- Then check the round as the wrapper would, because none ran: `python -c "import sys; print(len(open(sys.argv[1], encoding='utf-8').read().strip()))" "$S/review-NNN.md"` under 1,500 is a failed round, and so is one whose reads were refused, however long its answer is. Codex logs every refused command to stderr, and `grep -i "blocked by policy" "$S/review-NNN.err"` lists them: a refused write is the read-only sandbox doing its job, but refused reads (opening, listing or searching files) with none that succeeded are a round that reviewed nothing.
+ **Check report length and successful reads before accepting a review round.** No wrapper ran, so check it as the wrapper would:
- - **The prompt arrives on stdin, from the file the wrapper wrote** (`- < "<prompt file>"`). Here stdin is the prompt, so it is never `< /dev/null`; an empty or missing prompt file is a round that never started.
- - **No wrapper measures this run**, so the check above is the round's gate (the `independent-review` skill's bar: short, or unable to read, is failed).
+ ```bash
+ python -c "import sys; print(len(open(sys.argv[1], encoding='utf-8').read().strip()))" "$S/review-NNN.md"
+ grep -i "blocked by policy" "$S/review-NNN.err"
+ ```
- - **`--ephemeral`** saves no session, and a new `codex exec` starts from the prompt alone.
- - **`--ignore-user-config`** leaves out `~/.codex/config.toml`, and with it the MCP servers and tools it adds, which `-s read-only` would not bind: the sandbox covers only the shell commands the model runs (Codex CLI 0.159.0, `2026-10-29`). It also leaves out the model and, on Windows, the sandbox mode without which every read is refused, so both go back on the command line. (`2026-11-02`, Codex CLI 0.166.0 on Windows 11: with them the session read a file and was refused a write; without the mode it was refused both, "blocked by policy", and still answered in full sentences.) **`--ignore-rules`** skips the execpolicy rule files.
- - **What these flags were not shown to turn off:** Codex's instruction files, the repository's `AGENTS.md` and the one in `CODEX_HOME`. The round's report names them.
- - A short answer is a failed round, never a clean one, and the subject and prompt files are deleted when the round ends (the `independent-review` skill).
+ A report under 1,500 is a failed round. Refused reads with none successful also fail, however long the answer. Opening, listing and searching files are reads; a refused write is the read-only sandbox doing its job. Codex logs every refused command to stderr, where the `grep` command lists them.
+ - **Read the prompt from the file the wrapper wrote through stdin.** Use `- < "<prompt file>"`, never `< /dev/null`: stdin here is the prompt. An empty or missing prompt file means the round never started.
+ - **Use the manual check as the round's gate.** No wrapper measures this run; the `independent-review` bar fails a short round or one unable to read.
+ - **Start with `--ephemeral` so the review saves no session.** A new `codex exec` starts from the prompt alone.
+ - **Exclude user config and execpolicy rules from the review session.** `--ignore-user-config` omits `~/.codex/config.toml`, including its MCP servers and tools. The sandbox covers only shell commands the model runs; `-s read-only` does not bind those added tools (Codex CLI 0.159.0, observed 2026-10-29). It also omits the model and, on Windows, the sandbox mode without which every read is refused. Put both back on the command line. Observed on Codex CLI 0.166.0, Windows 11, 2026-11-02: with model and mode specified, a session read a file and was refused a write. Without the mode, both were refused as "blocked by policy", yet the session still answered in full sentences. `--ignore-rules` skips execpolicy rule files.
+ - **Name the instruction files still loaded in the round's report.** These flags were not shown to disable Codex's instruction files: the repository's `AGENTS.md` and the one in `CODEX_HOME`.
+ - **Treat a short answer as failed and delete the temporary review files.** It is never a clean round. Delete subject and prompt files when the round ends, as `independent-review` requires.
+
+ Each rule's origin, the case that taught it, is in `receipts.md` beside this file; read it when a rule's edge is unclear.
+
## How you can tell it worked
- Codex argued at least one point you then changed or defended, the run's header shows the session and model you meant, and any diff it reported is on disk and was reviewed by someone else.
+ Codex argued at least one point you then changed or defended, and the run's header shows the session and model you meant. Any diff it reported is on disk and was reviewed by someone else.
## Mechanics
- The script is this skill's own `<skill dir>/scripts/codex.py`, wherever the skill is installed (for the user, or vendored into a repository). Use its absolute path so it works from any cwd, and pass `--cwd` so the session is scoped to the right repository.
+ **Use the script's absolute path and scope its session with `--cwd`.** This skill owns `<skill dir>/scripts/codex.py`, whether installed for the user or vendored into a repository. Its absolute path works from any working directory.
| Command | Effect |
|---|---|
| `codex.py "<msg>"` | Send; auto-resume if a session exists, else start new |
| `codex.py --new "<msg>"` | Force new session |
| `codex.py --session ID "<msg>"` | Resume the session with that id (§ Resume or start fresh) |
| `codex.py --read FILE` | Read message body from FILE (`-` for stdin) |
| `codex.py --status` | Show whether a session is active and how long since last call |
| `codex.py --reset` | Clear the session marker (next call starts fresh) |
### Flags
| Flag | Default | Notes |
|---|---|---|
| `--new` | off | Force new session even if one is stored |
| `--session ID` | — | Resume that session in `--cwd`, with no fallback to a new one. The model comes from `--model`, or from the marker when it names this session. |
| `--read FILE` | — | Read message body from FILE (`-` for stdin). Use for long context-rich openings. |
| `--model MODEL` | codex's configured default | Override the model. Pass one only to pin the newest model the Codex CLI offers when the configured default (`~/.codex/config.toml`) is not it. Remembered for the session and re-sent on every resume. |
| `--effort LEVEL` | `xhigh`, on every turn | `low` / `medium` / `high` / `xhigh`, sent as `-c model_reasoning_effort=…`. |
- | `--sandbox MODE` | `read-only` | `read-only` / `workspace-write` / `danger-full-access`. **New sessions only** — `exec resume` inherits sandbox from the original session. |
+ | `--sandbox MODE` | `read-only` | `read-only` / `workspace-write` / `danger-full-access`. New sessions only — `exec resume` inherits sandbox from the original session. |
| `--cwd DIR` | current directory | Directory the codex run happens in. Required to drive a repo other than the one the caller is sitting in, and it also scopes session continuity (below). Fails loudly if `DIR` is not a directory. |
| `--raw` | off | Pass through raw codex output (default strips the codex header block) |
### Session continuity
- A marker at `~/.claude/.codex_agents_active` (override with `$CODEX_AGENTS_STATE`) records the active session's directory, model and id, and the wrapper resumes that id (`codex exec resume <id>`), so the default is "continue" until `--reset` or `--new`. Not `--last`: that takes the newest session codex recorded in the run's directory (`--all` lifts that; codex 0.159, checked 2026-10-22), whoever started it, such as a `--new` consult run there. A marker written before ids were recorded resumes with `--last` once and records the id of whatever that picked; if that is not the stage's session, `--session` puts it right.
+ **Resume the recorded id rather than whichever session ran most recently.** The marker at `~/.claude/.codex_agents_active`, overridden by `$CODEX_AGENTS_STATE`, records the active directory, model and id. The wrapper uses `codex exec resume <id>` and continues until `--reset` or `--new`. `--last` instead takes the newest session Codex recorded in that directory, whoever started it, including a `--new` consult. `--all` lifts that directory scope (codex 0.159, checked 2026-10-22). A marker predating recorded ids uses `--last` once and records the selected id. If it picked the wrong stage session, correct it with `--session`.
- **The marker names the last session codex opened for the directory, whether the run then succeeded or failed.** Codex prints the header naming a session only once it has opened it. So a usage limit, which fails a run after the session took the turn, leaves the marker on that session — a new one included, since it holds the brief and the work so far — and the next call continues it; `--new` starts over. A resume falls back to a new session only when codex could not open the old one: no rollout left for its id, which fails with no header. When it could, a failed resume exits with the error, because a new session would start without the stage.
+ **The marker names the last session Codex opened, including failed runs.** Codex prints a session header only after opening it. A usage limit fails after the session takes the turn, so the marker keeps that session, including a newly opened one. It holds the brief and work so far; the next call continues it, while `--new` starts over. Resume falls back to a new session only when Codex couldn't open the old one: no rollout remains, so it fails without a header. Otherwise, a failed resume exits with its error rather than starting without the stage.
- **Sessions are scoped to the working directory.** The marker is one file per user, so it records which directory it belongs to, and a run resumes only when the directory matches; otherwise it starts a fresh thread. Without that, delegating into a second repo would resume a conversation the wrapper never had there. One marker holds one directory, which is why parallel builds each need their own (§ Resume or start fresh). `--status` tells you when a session exists but belongs to another directory. A legacy bare-timestamp marker (written before `--cwd` existed) counts as "no session here", so the first run after this change starts new.
+ **Sessions are scoped to the working directory.** The per-user marker records its directory and resumes only when that matches; otherwise it starts fresh. Without that check, a second repository would resume a conversation the wrapper never had there. One marker holds one directory, so parallel builds need their own (§ Resume or start fresh). `--status` reports a session belonging to another directory. A legacy bare-timestamp marker predating `--cwd` counts as no session here, making the first run after this change new.
- **A resume does not keep the session's model.** `codex exec resume` takes its model from `~/.codex/config.toml`, not from the session it resumes, and says so only in the run's header — so a session started with `--model` and continued without it silently answers on the config default. The wrapper records the model a session started with, re-sends `-m` on every resume, and writes the model codex reports to stderr after each run, with a warning when it differs from the one requested. Read that line before trusting a round. When calling `codex exec resume` directly, pass `-m <model> -c model_reasoning_effort=<level>` every time. (`2026-10-01`: a resumed session came back on the config default, and nothing failed to say so.)
+ **A resume does not keep the session's model.** `codex exec resume` takes its model from `~/.codex/config.toml`, not the resumed session, and reports it only in the header. A session started with `--model` and resumed without it silently uses the config default. The wrapper records the starting model, re-sends `-m` on every resume and prints the reported model to stderr after each run. It warns when that differs from the request. Read that line before trusting a round. Direct `codex exec resume` calls must pass `-m <model> -c model_reasoning_effort=<level>` every time.
### Codex binary lookup
- Auto-locates, in order:
- 1. `$CODEX_BIN` env var (if set and the path exists)
- 2. `codex` on PATH — for the npm package, the native binary its shim runs, so a long prompt never passes through `cmd.exe`
- 3. OpenAI ChatGPT VS Code extension bundle (`~/.vscode/extensions/openai.chatgpt-*/bin/<arch>/codex[.exe]`)
+ **Use the configured binary, installed CLI, then the extension bundle.** Automatic lookup tries these in order:
- The installed CLI comes first because it is the one you install and update; the extension ships whatever build it pins. (`2026-10-22`: the extension's bundle was a 0.155 alpha without `codex-code-mode-host.exe`, and every tool call of a build round failed before it ran, with no file changed.)
+ 1. `$CODEX_BIN` when set to an existing path.
+ 2. `codex` on PATH. For the npm package, use the native binary its shim runs so a long prompt never passes through `cmd.exe`.
+ 3. The OpenAI ChatGPT VS Code extension bundle: `~/.vscode/extensions/openai.chatgpt-*/bin/<arch>/codex[.exe]`.
- Works on Windows and macOS (and Linux if the extension or PATH provides the binary).
+ The installed CLI comes first because you install and update it; the extension ships its pinned build. This works on Windows and macOS, and on Linux if PATH or the extension provides the binary.
### Cost
- Uses whichever account the Codex CLI is signed in to (`codex login`). On a ChatGPT subscription there is no per-call API charge, which makes routine peer-ideation cheap; check your own plan's limits.
+ **Check the signed-in account's plan and usage limits.** The wrapper uses the account signed into the Codex CLI through `codex login`. A ChatGPT subscription has no per-call API charge, making routine peer ideation cheap; check your own plan's limits.
### Why it works this way (gotchas captured)
- - **Piped, codex writes its metadata header — workdir, model, session id — to stderr, and the answer alone to stdout.** The wrapper reads the model and the session id from that header, records the id for the next resume and prints both after each run. It strips a header from stdout only when the block between two `----` lines is one, so an answer with two horizontal rules is never cut. (`2026-10-22`, codex 0.159.)
- - **`-s SANDBOX` is an exec-level flag, not valid on `exec resume`**, which inherits the sandbox; the wrapper splits into a new-session path (with it) and a resume path (without). **Outside a git repository a resume also needs `--skip-git-repo-check`**, or codex refuses it ("Not inside a trusted directory") and the wrapper falls back to a new session — the conversation is lost and only the stderr says so. The wrapper adds the flag there and only there. (`2026-10-21`, a live test of the wrapper in a scratch folder.)
- - **Stdin must be closed** (subprocess `input=""`) or codex hangs waiting for interactive input.
+ - **Read the piped run's metadata from stderr and answer from stdout.** The header contains workdir, model and session id (codex 0.159, observed 2026-10-22). The wrapper reads model and id, records the id for resume and prints both after each run. It strips a stdout header only when the block between two `----` lines is a header. An answer with two horizontal rules is never cut.
+ - **Pass `-s SANDBOX` only to new sessions, not `exec resume`.** It is an exec-level flag; resume inherits the sandbox. The wrapper separates new-session and resume paths accordingly. Outside a git repository, resume also needs `--skip-git-repo-check` (observed in a live scratch-folder wrapper test, 2026-10-21). Without it, Codex refuses with "Not inside a trusted directory" and the wrapper falls back to a new session. The conversation is lost, and only stderr says so. The wrapper adds this flag there and only there.
+ - **Close stdin so Codex does not wait for interactive input.** Use subprocess `input=""`.