| name | codex-review |
| description | Drive interactive Codex sessions in WezTerm — to get a second opinion / review from Codex on ANY artifact (code, a design, an analysis, a document, a script), to validate a design or scope a phase with Codex BEFORE implementing, and to ask Codex ad-hoc questions. Use when the user asks Claude to have Codex review something (code OR a design/analysis/document/artifact), get a second opinion from Codex, run a Codex review gate/loop, codex-review a script before running it, validate/scope a design with Codex before building, ask Codex a question, relay a question to Codex, use WezTerm for Codex, or apply a Codex GO / FIXES_REQUIRED review workflow. A review is artifact-agnostic — never assume it is a "code review". Reviews run in a fresh interactive session that writes its review to a file and replies DONE; questions (incl. design consultations) run in one reusable interactive session. |
Codex via WezTerm (Claude → Codex)
Use this when the user wants Codex to either (a) review Claude's work — a code
change, a script before you run it, or a written artifact — or (b) answer a question.
Both run as real interactive codex TUIs in standalone WezTerm GUI windows
(wezterm start --always-new-process -- codex), driven through wezterm cli send-text /
get-text. This is the inverse of the claude-wezterm-review Codex skill (there Codex asks
Claude; here Claude asks Codex).
Everything goes through one helper:
/home/pierre/.claude/skills/codex-review/scripts/codex_session.sh
Two modes
| Mode | Session | Launched with | Output |
|---|
Questions (ask) | one reusable session per working directory (default name qa-<dir>-<hash>, auto-(re)started if never opened or the user closed it) | codex --dangerously-bypass-approvals-and-sandbox (so Codex can write the answer file unattended) | a self-contained Q&A file (question + answer) Codex writes, saved under <cwd>/qa/<timestamp>-<slug>.md; Codex replies only DONE |
Reviews (review) | a fresh, unique session per review, closed on success | codex --dangerously-bypass-approvals-and-sandbox (so Codex can write the review file unattended) | a review file Codex writes itself; Codex replies only DONE |
Keep the current model
If Codex pops its "Approaching rate limits — switch to a cheaper model?" modal, the
script dismisses it with Esc, which keeps the current model (it never presses Enter,
which would switch). The plain "weekly limit left" banner is just a notice and is ignored.
Do not switch models on the user's behalf.
Asking a question
/home/pierre/.claude/skills/codex-review/scripts/codex_session.sh ask \
--text "In one sentence, what does the -ngl flag do in llama.cpp?"
- Reuses the Q&A session for the current working directory — the default session name is
derived from the resolved cwd (
qa-<dir>-<hash>), so a pane opened in project A is never
reused for questions asked from project B (Codex's workspace root is fixed at launch and
scopes its file reads). Ask twice from the same folder → same pane (history preserved); ask
from a new folder → its own pane. Pass --session NAME to force a specific session, or
--cwd DIR to target/launch in a different directory. codex_session.sh name [--cwd DIR]
prints the session name a folder maps to.
- The script appends an instruction telling Codex to write its complete answer to a file under
<cwd>/qa/<timestamp>-<slug>.md and reply only DONE, then waits, keeping the current model
if the switch-model modal appears. It then folds the question into the same file (## Question /
## Answer) so each Q&A is a durable, browsable record in the project's qa/ folder, and prints
it. The file holds the whole answer (robust for long answers — a live pane scrape only captures the
visible viewport and silently truncates).
- Completion is now handled by the script — trust its return. Codex streams the file while still
composing, so a non-empty file alone can be a partial/truncated answer. The script no longer
keys on that:
wait_written waits until the Codex turn has finished generating and the file is
written before it returns (it does not grep the pane for DONE, because the instruction it sends
literally contains "reply with exactly: DONE" and would false-match). So when the ask command
returns and prints the Q&A file, the answer is complete — no manual pane check needed. (If you ever
need to inspect a still-running turn, codex_session.sh list gives the alive session and its
.env holds SOCK/PANE.) (See [[codex-ask-done-signal]].)
- Read Codex's answer from the printed file contents (the script
cats the Q&A file) and relay
it to the user. If Codex does not write the file within the timeout, the script falls back to
saving the question + a pane-tail scrape (which may be truncated) to the same qa/ record and
exits non-zero.
- The
qa/ folder lives in the working directory (the project), so Q&A history is kept with the
code rather than in /tmp. Add qa/ to .gitignore if you don't want it tracked.
Ask as a design / scoping gate — BEFORE you build, not only after
The highest-leverage use of ask is a design consultation before implementing a large or
architectural change — a design Codex validates is far cheaper than a review that rejects code you
already wrote. For each substantial phase, send a --prompt-file that:
- names the change and points Codex at the real source it should verify against (existing types,
traits, call sites), with an explicit "read the code; don't trust my prose";
- states your proposed design concretely (the new types/SQL/algorithm), then asks numbered
questions about the consequential decisions (schema/contract changes, lock/ordering, invariants);
- for a big phase, asks Codex to SCOPE the minimal testable slice vs what to defer (ops/later),
so you don't over-build — this repeatedly turned a sprawling phase into a tight, reviewable one.
Codex answers with a verdict like "GO with adjustments" + a numbered list; apply the adjustments
before writing code. Across a multi-phase build this caught real architecture bugs (a wrong
primary key, a generation-label compatibility gap, a verify path that needed to be read-only, a
retention model) that a post-hoc review would have forced a full rewrite to fix. This is the
[[ask-codex-before-important-decisions]] discipline operationalised: consult before the
consequential/irreversible choice, not after.
Running a review
The review contract: you write an instructions file; Codex reads it, writes its review to a
file under a reviews folder, and replies only DONE.
Why keep the instructions minimal — the whole point is "unknown unknowns".
By the time you ask for a review you have tête dans le guidon (French: "head in the handlebars" —
so absorbed in the task that you can't see what's around you). You've been deep in the work; your
mental model is exactly the set of things you already thought about — and your blind spots are, by
definition, invisible to you. If you hand Codex a checklist ("verify X, Y, Z", "look at these
files/lines", "I'm worried about A and B"), you project your own narrowed view onto the reviewer:
it spends its budget confirming your assumptions and tends to miss everything outside your field of
view — which is precisely where the real bugs you didn't anticipate live. An independent reviewer's
entire value is the perspective you can't have on your own work; over-specifying collapses that back
into your view and defeats the purpose. So give Codex the artifact + one line of what it is, and let
it discover the change and the risks itself. This is not laziness — it is the mechanism that surfaces
the unknown unknowns. (Borne out repeatedly: the sharpest findings — an object-safety contradiction,
a topology leak, a wrong-authority naming — came from unguided reviews; a checklist would never have
listed them.) Trust the reviewer to see what you can't.
A review is artifact-agnostic. It may be code, a design, an analysis, a written document, or a
script — never assume it is a "code review". Say what is being reviewed in the instructions; the
script's own prompt no longer hardcodes "code review". Steps that only make sense for code (the
validation in step 0) simply don't apply when the artifact is a document.
-
(Code only) Run your own validation first (build + fmt + lint + tests) and fix what it finds, so
the review spends its budget on contract/logic, not on compile errors you could have caught. State
the exact commands you ran and that they're green in the instructions. (Skip for a doc/design review.)
-
Write the review instructions to a file. Do not use /tmp — write it in the project,
alongside its review output and with a unique name so concurrent reviews and re-reviews never
clobber each other's prompts and the instructions stay as a durable record next to the review:
<workdir>/reviews/YYYY-MM-DD-<topic>-codex-instructions.md (add -r2, -r3, … for re-reviews,
mirroring the review file's suffix). Uniquify with the topic + date (+ round); if a same-named
file could still exist, append a short timestamp (date +%H%M%S). Add reviews/ to .gitignore
if you don't want these tracked. The file contains:
- repo path and exact scope (the files / diff / artifact to review);
- user intent and non-negotiable constraints;
- validation already run (the green commands from step 0);
- what to verify against source (API arg names, response fields, return/shutdown
semantics — not just style), with an explicit "verify against source, not the diff prose";
- a request to audit the tests for false-green holes — a test that would still pass if the
behaviour regressed (a too-narrow snapshot, a fixture that masks the bug, a substring assert).
This caught real gaps repeatedly; it is as valuable as the source check;
- a request that every finding (BLOCKER, WARN, and NIT alike) come with a concrete,
actionable recommended fix — because all severities get applied afterwards, not just the
blocking ones;
- any deviation you made from an earlier design/
ask answer, stated explicitly with your
reason, and a request that Codex confirm it's acceptable or push back (honest disclosure beats
having it discovered);
- the required output structure, ending in a final line that is exactly
VERDICT: GO or VERDICT: FIXES_REQUIRED.
Keep instructions minimal — first review AND re-review. For a first review, name the scope
(what the artifact is) and let Codex discover the change/risks independently (per
[[codex-review-no-explicit-instructions]]). For a re-review after FIXES_REQUIRED, do not
enumerate each finding and how you fixed it (that over-directs and biases Codex toward your framing).
Instead point it at its own prior review file + the artifact, say the findings have been
addressed, and let it re-verify independently. Codex reads the prior review itself — you don't
re-state it.
You do not put the "save to file / reply DONE" wording here — the script's prompt
already tells Codex to read this file, write the review file, and reply DONE.
-
Launch the review (in the background, Bash run_in_background: true, so it does not block
the turn):
/home/pierre/.claude/skills/codex-review/scripts/codex_session.sh review \
--workdir /path/to/repo \
--instructions-file /path/to/repo/reviews/YYYY-MM-DD-topic-codex-instructions.md \
--review-file /path/to/repo/reviews/YYYY-MM-DD-topic-codex-review.md
The script opens a fresh interactive Codex (bypass on so it can write files), tells it
to read the instructions file and write the review to --review-file, then waits for it,
keeping the current model if asked. On success it prints the path + any VERDICT: line and
closes the window (pass --keep-open to leave it up). It refuses to start if the review
file already exists, so it never stomps a finished review. The script returns only after the
review is complete — wait_written waits for the Codex turn to finish generating and the review
file to be fully written, closing the old streamed-partial-file race, so the printed VERDICT: line
is trustworthy the moment the command returns (see [[codex-ask-done-signal]]).
-
After the review file appears, read it and apply Codex's recommendations across ALL
severities — not only the BLOCKERs. Address every BLOCKER, WARN, and NIT whose fix is
compatible with the user's intent and constraints; the verdict only reflects what blocks
it, but the non-blocking WARN/NIT suggestions are part of the review and should be applied
too (as was done here: the -c BLOCKER and the preflight-check NIT). If you deliberately
skip a recommendation (out of scope, conflicts with a stated constraint, or you disagree),
say so explicitly rather than silently dropping it — and when a suggestion is a judgment
call, you may ask Codex (ask) or the user before applying. Then, by verdict:
FIXES_REQUIRED: after applying, rerun checks and launch a new review artifact
(...-codex-review-r2.md) to confirm a clean GO.GO: still apply the compatible WARN/NIT suggestions; no re-review of the same step
needed.
Waiting, monitoring, and recovery
Launch reviews in the background (run_in_background: true) and wait for the command's own
completion notification — the script returns only after the turn has finished generating and the
review file is fully written (wait_written), so its return is the completion signal. Do not
poll until [ -s <review-file> ] yourself: Codex streams the review file while composing, so a
non-empty file can still be partial — that check is exactly what the script no longer relies on. The
verdict notification is your cue to read the review and act.
ls -l <review-file>
/home/pierre/.claude/skills/codex-review/scripts/codex_session.sh list
WEZTERM_UNIX_SOCKET=<sock> wezterm cli get-text --pane-id <pane> | tail
cat /tmp/codex-sessions/<session>.launch.log
Verify the launch actually came up. The GUI launch can fail at startup (e.g. a WezTerm/Wayland
hiccup) — the background command returns, but no Codex is running. A few seconds after launching,
confirm the review session is ALIVE via codex_session.sh list. This distinguishes two cases that
need OPPOSITE responses:
- Running but slow (session
ALIVE, review file not yet there): a normal review in progress —
wait, do NOT relaunch. If it later times out, the script leaves the window open and prints the
sock/pane + pane tail; inspect or keep waiting — still do not relaunch the same review file.
- Died at launch (session NOT in the
ALIVE list AND the review file never appears, often with a
GUI-teardown tail in the .launch.log): the launch failed before Codex started — retrying is
safe and correct. The script refuses to start if the review file already exists, so a retry can
never stomp a finished review; relaunch the same command.
Session management
codex_session.sh name
codex_session.sh start
codex_session.sh list
codex_session.sh stop --session NAME
The reusable Q&A session is per working directory by default (name qa-<dir>-<hash>), so
each project gets its own correctly-rooted pane; --session NAME overrides. State lives in
/tmp/codex-sessions/<name>.env (override dir with $CODEX_SESSION_STATE_DIR). A session is
"alive" when its GUI pid is running and its wezterm cli socket answers; if the user closes
the window, the next ask transparently launches a fresh one for that folder.
Why ask Codex to verify against source
Codex reads the actual repository, so its value over a style pass is contract verification:
ask it to confirm protocol/API assumptions (argument names, response field names, return
shapes, shutdown semantics) against the real source. That catches the bugs that make a run
produce wrong numbers or hang — not just formatting. Put these "verify against source" asks in
the instructions file.
