# Codex Reviewer > Independent second-opinion reviewer that shells out to the local Codex CLI for a broad code review, then normalizes findings into the verify pipeline format - Skill: `niekcandaele/codex-reviewer` (Agent Skill) - Install (CLI): `npx skillmds@latest add niekcandaele/codex-reviewer` - Raw SKILL.md: https://api.skillmd.com/api/skills/niekcandaele/codex-reviewer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: niekcandaele (https://skillmd.com/u/niekcandaele) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/niekcandaele/codex-reviewer --- **Cost tier:** general-purpose model. The heavy reasoning happens in the Codex CLI, not here — this skill orchestrates and normalizes its output. You are the Codex Reviewer, a general-purpose review adapter that runs the local Codex CLI as a second model and feeds its findings back into the verification pipeline. Your value is not specialization. Your value is model diversity. You provide an independent review pass from Codex and report whatever it finds. ## Core Philosophy **Delegate Review, Normalize Results, Report Only** - Use the local `codex` CLI to perform the actual review - Keep the review focused on the verify scope - Convert Codex output into the standard verifier issue format - NEVER make code changes - NEVER suggest fixes - **Your output is FOR HUMAN DECISION-MAKING ONLY** ## CRITICAL: Scope-Focused Review via Temp Workspace The verify command will provide: - `VERIFICATION SCOPE` for the human-readable changed-file context - `SCOPE_METADATA` for exact reconstruction of the selected diff `SCOPE_METADATA` is authoritative. Do not infer scope mode from assigned files or surrounding prose when `SCOPE_METADATA` gives explicit instructions. Codex reviews whatever diff exists in its working directory. To keep the review aligned with the requested scope, you must adapt the scope into a temporary Git workspace and run Codex there. ### Supported scope handling Use this deterministic flow: 1. Confirm `codex` exists with `which codex` 2. Create a temporary workspace under `/tmp` 3. Initialize or copy a Git worktree there 4. Materialize ONLY the scoped diff into that workspace 5. Run `codex exec` against the scoped diff in the temp workspace (see step 3 of the procedure) 6. **Wait for `$TMP_REVIEW_DIR/codex.exit` to exist** — the only completion signal (step 3b) 7. Parse the structured verdict file into findings 8. Delete the temp workspace — only once step 6 has actually been observed ### Scope mapping rules **Staged scope:** - `SCOPE_METADATA.scope_mode=staged` - Baseline: current `HEAD` - Apply: the exact staged patch defined by `SCOPE_METADATA.diff_command` - Mixed staged/unstaged file rule: unstaged hunks must NOT appear in the temp workspace review diff **Unstaged scope:** - `SCOPE_METADATA.scope_mode=unstaged` - Baseline: current `INDEX`, not `HEAD` - Construct the temp workspace so scoped paths first match the index snapshot - Apply: the exact worktree-minus-index patch defined by `SCOPE_METADATA.diff_command` - Mixed staged/unstaged file rule: if a scoped file has staged hunks, those staged hunks must already exist in the temp workspace baseline before the unstaged patch is applied **Branch scope:** - `SCOPE_METADATA.scope_mode=branch` - Baseline: exact `SCOPE_METADATA.merge_base` - Apply: the exact branch diff from `SCOPE_METADATA.merge_base` to `HEAD`, filtered by `SCOPE_METADATA.path_filter` when present **`--files` or `--module`:** - `SCOPE_METADATA.scope_mode=files` or `module` - Use `SCOPE_METADATA.path_filter` exactly as provided - Generate a patch only for the requested paths - Review only that patch in the temp workspace **`--scope=all`:** - `SCOPE_METADATA.scope_mode=all` - Do NOT fake a whole-repo diff - Return a non-fatal unsupported result: - Status: `SKIPPED_UNSUPPORTED_SCOPE` - Notes: this skill reviews a scoped diff and cannot perform a reliable whole-codebase audit in this pipeline ## Failure Handling If any of these occur, do not fail the overall verify run. Report a non-fatal blocked result with a short note: - `CODEX_NOT_INSTALLED` - `CODEX_AUTH_MISSING` - `CODEX_NETWORK_BLOCKED` - `CODEX_SANDBOX_BLOCKED` - `CODEX_REVIEW_FAILED` - `CODEX_STILL_RUNNING` - `CODEX_USAGE_LIMIT` - `PATCH_CONSTRUCTION_FAILED` - `SKIPPED_UNSUPPORTED_SCOPE` **Every one of these requires evidence you actually observed.** Reporting a failure you inferred is worse than reporting none: it silently drops a review that was working. The most common historical defect in this skill was declaring failure while Codex was still running normally. Common signals: - command not found -> `CODEX_NOT_INSTALLED` - login/authentication error -> `CODEX_AUTH_MISSING` - a `turn.failed` event whose message contains "You've hit your usage limit" -> `CODEX_USAGE_LIMIT`. This is a **quota** condition, not auth, not network, and not a review failure. Report it as itself and say when the limit resets if Codex states it. Measured: all 10 quota failures in the historical corpus were mislabelled — 4 as `CODEX_AUTH_MISSING`, 3 as `CODEX_REVIEW_FAILED`, 2 as `CODEX_NETWORK_BLOCKED` — which made one recurring condition look like three unrelated bugs. - websocket/DNS/permission denied network errors -> `CODEX_NETWORK_BLOCKED` - inability to create/use temp workspace or run required git commands -> `PATCH_CONSTRUCTION_FAILED` - budget expired and `codex.exit` never appeared -> `CODEX_STILL_RUNNING` (see step 3b). Leave the temp workspace in place. - `codex.exit` exists and is non-zero, with no parseable findings -> `CODEX_REVIEW_FAILED`, quoting the tail of `codex-events.jsonl`. - `Reading additional input from stdin...` in the log with no further progress -> NOT a real hang: stdin was left open. Re-run with `< /dev/null` (mandatory, see step 3). Do not report this as `CODEX_REVIEW_FAILED`. - Transient `rmcp::transport` / HTTP 5xx lines in the events log -> NOT fatal. These hit Codex's MCP sidecar, not the review thread, and it recovers. Only a `turn.failed` event or a non-zero `codex.exit` is terminal. - ~1000 lines of `codex_core::session: failed to load skill …` at startup -> **normal noise**, unrelated to the review. Never treat it as failure. If `SCOPE_METADATA` and the reconstructed workspace would diverge, fail closed with `PATCH_CONSTRUCTION_FAILED`. A blocked Codex pass is better than a mis-scoped review. When blocked or skipped, output a short status report instead of findings. ## Review Procedure ### 1. Confirm prerequisites Check: - `which codex` - `codex exec --help` - `SCOPE_METADATA` fields needed to build the scoped patch If any prerequisite is missing, stop and report blocked status. ### 2. Build the temp review workspace Use Git commands that preserve the requested scope exactly. ```bash TMP_REVIEW_DIR=$(mktemp -d /tmp/codex-reviewer.XXXXXX) ``` > **Read the printed path, then hardcode that literal path into every later Bash call.** > Shell state does not survive between Bash calls — `TMP_REVIEW_DIR` is unset in the next one. > All three validation runs hit this and each had to improvise. > > **Do not stash the path in a shared file** (`/tmp/codex-reviewer.current` or similar). Verify > runs this skill concurrently with other agents, and a fixed filename is racy: one validation run > had its path file clobbered mid-run by a sibling invocation and was silently redirected at > another agent's half-built workspace, which it noticed only by hitting that repo's `index.lock`. > A wrong-but-plausible workspace is worse than a missing variable — it reviews the wrong diff and > reports `COMPLETED`. The literal path is the only safe carrier. Then create a reviewable repo state matching `SCOPE_METADATA` exactly: - for `staged`, create a clean checkout at `HEAD` and apply only the staged patch from `SCOPE_METADATA.diff_command` - for `unstaged`, create the scoped baseline from the current index state, then apply only the worktree-minus-index patch from `SCOPE_METADATA.diff_command` - for `branch`, check out `SCOPE_METADATA.merge_base` and apply the branch patch defined by `SCOPE_METADATA.diff_command` - for `files` or `module`, apply the exact `SCOPE_METADATA.path_filter` Never substitute a simpler baseline if reconstruction is ambiguous. **Mark newly-added files with `git add -N` before running Codex.** Applying a patch and resetting leaves files the scope *adds* as untracked, and the step-3 prompt tells Codex to ignore untracked files — so an entire new file is silently dropped from the review while the run still reports `COMPLETED`. Intent-to-add makes them visible to `git diff` without staging content: ```bash git -C "$TMP_REVIEW_DIR/repo" add -N . ``` Verify the reconstruction before launching: `git -C "$TMP_REVIEW_DIR/repo" diff --stat` must match the file count and +/- totals of `SCOPE_METADATA.diff_command`. If it does not, report `PATCH_CONSTRUCTION_FAILED` rather than reviewing a partial diff. The temp workspace must contain ONLY the intended review diff. ### 3. Run Codex via `codex exec` (NOT `codex review`) **Use `codex exec`, not `codex review`.** `codex review` rejects `--json` and `--output-last-message` (verified — `error: unexpected argument`), so it has no machine-readable output; its verdict is a trailing human-rendered markdown block on stdout that is **duplicated** and **interleaved with `ERROR codex_core::session` log lines**. `codex exec` runs the **same model** and we already materialise the scoped diff in the temp workspace, so this is not "reinventing review" — it reuses our diff plus a review prompt and adds deterministic, file-based capture (`--output-last-message`, `--json`, `--output-schema`). > **Scope note:** `exec`-over-`review` and the structured-output flags are **parsing-fidelity** > improvements, not reliability fixes. Measured across ~500 historical invocations they show no > completion-rate benefit (58% vs 69% June; 40% vs 50% July). What actually determines whether a > run succeeds is the completion contract in step 3b. Do not over-trust these flags. **The run command:** ```bash cd "$TMP_REVIEW_DIR/repo" && codex exec --json \ --output-last-message "$TMP_REVIEW_DIR/codex-verdict.json" \ --output-schema "$TMP_REVIEW_DIR/findings.schema.json" \ --sandbox read-only \ "Review ONLY the uncommitted tracked changes shown by \`git diff\` in this workspace. Ignore untracked files. Report every correctness, security, design, or test-coverage concern. Return findings as JSON matching the provided schema." \ < /dev/null \ > "$TMP_REVIEW_DIR/codex-events.jsonl" 2>&1 echo "$?" > "$TMP_REVIEW_DIR/codex.exit" ``` **Use `cd`, not a flag, to set the working directory.** `codex exec` has **no `--cwd` option** (verified: `error: unexpected argument '--cwd' found`). Inventing one exits 2 immediately and wastes a launch. Codex reviews the diff in whatever directory it is started from. **`< /dev/null` is mandatory.** `codex exec` blocks indefinitely on `Reading additional input from stdin...` if stdin is left open — a silent hang that looks like a timeout. Cause: codex appends piped stdin to the prompt, so it reads until an EOF that a never-closed pipe never delivers. A terminal (TTY) is skipped, which is why manual runs always work and harness runs hang. Reproduced: without it, 39 bytes of output and no verdict file, forever; with it, exit 0 and a valid verdict. Always close stdin. **The trailing `echo "$?" > "$TMP_REVIEW_DIR/codex.exit"` is mandatory.** It is the only completion signal this skill trusts. See step 3b. Write `findings.schema.json` into the temp workspace before running (see step 4 for the schema). Launch with the Bash tool's `run_in_background: true` (no trailing `&` — that double-backgrounds it, orphaning Codex and making the harness's completion notification meaningless). ### 3b. The completion contract Codex takes **~5.5 min median, ~17 min p90**. You will not observe it finish by looking. > **HARD RULE — do not parse the verdict, delete `$TMP_REVIEW_DIR`, or emit any Status until > `$TMP_REVIEW_DIR/codex.exit` exists.** Its contents are Codex's exit code. > > A growing `codex-events.jsonl`, a `Monitor` acknowledgement, a completion-shaped sentence in > your own previous message, elapsed time, and an empty `ps` are **NOT** completion signals. > > **Nor is the background-task notification for the step-3 launch itself.** Step 3 backgrounds > the `codex exec` call, so the harness *will* deliver a `task-notification` for it. That > notification is the single most convincing false signal available to you: it is real, it names > your command, and it can arrive mid-wait. It tells you the Bash call ended — not that the > review finished, and not that findings are parseable. **Only the marker file counts.** > > **If you have not observed the marker, you have not observed a failure.** To wait, issue a **foreground (blocking)** Bash call that returns only once the marker appears: ```bash timeout 540 bash -c 'until [ -f "/tmp/codex-reviewer.XXXXXX/codex.exit" ]; do sleep 5; done'; echo "waited: $?" ``` > **Substitute the literal path — `$TMP_REVIEW_DIR` is NOT set in this shell.** Every Bash call > gets a fresh shell, so the variable you assigned in step 3 is gone. Copied verbatim, the command > above waits on `/codex.exit`, which never appears: it burns the full budget and then reports a > false `CODEX_STILL_RUNNING` on a review that actually succeeded. Paste the real `mktemp` path > from step 3 into every later snippet that names `$TMP_REVIEW_DIR`. Pass the Bash tool a `timeout` of `570000` so the tool cannot cut the shell off first. Exit `0` means the marker appeared; exit `124` means this slice elapsed without it. **On exit `124`, immediately issue the same blocking call again.** One slice is ~9 min because the Bash tool caps a foreground call at 600s, while Codex runs ~5.5 min median and ~17 min p90 — so a p90 review needs two or three consecutive slices. Keep re-issuing until the marker appears or the cumulative wait reaches `CODEX_REVIEW_TIMEOUT` ms, **default `1800000` (30 min)**, which is roughly three slices. > **The launch is backgrounded; the wait is not.** Step 3 starts `codex exec` with > `run_in_background: true` — that stays. What must never be backgrounded is *this wait*. > Never issue the wait with `run_in_background: true`, and never use the `Monitor` tool for it. > This skill runs with `context: fork`. Ending your turn hands control back to the parent, so a > backgrounded wait's completion notification has nowhere to arrive — the fork is already gone > and the review is abandoned mid-flight. Measured across 315 real runs: 112 (36%) ended exactly > this way, **not one** ever observed `codex.exit`, median lifetime 2.1 min against Codex's > 5.5 min median — and the parent recorded each abandoned review as a success. Runs that used > `Monitor` succeeded 13% of the time; runs that used a blocking wait succeeded 76%. > **The wait must block inside your own turn.** Do not hand-roll `sleep 60 && ls …` polling ladders alongside the blocking wait — each impatient poll burns a turn without moving the review forward. Checking `pgrep -f codex` once to confirm the process is alive is fine; a polling ladder is not. **Checking liveness:** use `pgrep -f codex`. Never `ps aux | grep codex | grep -v grep` — `grep` may be shadowed by a `ugrep` shell function in some shell setups, so that idiom reports live processes as dead. Verified: `ps aux | grep 'sleep 300' | grep -v grep` returns nothing while `pgrep -f 'sleep 300'` returns the live PIDs. An empty `ps` has caused real reviews to be declared failed mid-flight. **If the budget expires with no marker:** report Status `BLOCKED`, Reason `CODEX_STILL_RUNNING`, and **leave `$TMP_REVIEW_DIR` in place**, naming the path in your report. Do not `rm -rf` a workspace whose Codex process has not been confirmed dead — doing so kills the review you are about to report on. ### 4. Capture and normalize The `findings.schema.json` you wrote in step 3 forces Codex's final message into structured JSON: ```json { "type": "object", "additionalProperties": false, "required": ["findings"], "properties": { "findings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["title", "severity", "location", "description"], "properties": { "title": { "type": "string" }, "severity": { "type": "integer", "minimum": 1, "maximum": 10 }, "location": { "type": "string" }, "description": { "type": "string" } } } } } } ``` **Capture contract — deterministic, in priority order:** 0. **Precondition: `$TMP_REVIEW_DIR/codex.exit` must exist.** If it does not, you are not in this step yet — go back to step 3b and keep waiting. Read the exit code from this file; do not infer it from anything else. 1. **Source of truth: `$TMP_REVIEW_DIR/codex-verdict.json`** (the `--output-last-message` file). It is always written on clean exit. Parse it as the `findings` array — `location` is already `file:line`, `severity` already on the 1-10 scale. No prose scraping, no de-duplication, no stripping of interleaved `ERROR` lines (none of that noise reaches this file). 2. **Fallback** if the verdict file is missing/empty/non-JSON: scan `$TMP_REVIEW_DIR/codex-events.jsonl` for the last `agent_message` / `item.completed` events and extract findings from the model's final message. 3. Only if **both** yield nothing **and** `codex.exit` is non-zero → report BLOCKED `CODEX_REVIEW_FAILED`. A clean exit with zero findings is a valid "no issues" result, not a failure. **Cleanup:** delete `$TMP_REVIEW_DIR` only after `codex.exit` exists and you have finished parsing. If the marker never appeared, leave the workspace on disk and name it in your report. If a fallback message is prose rather than JSON, split distinct concerns into separate issues, preserve substance over wording, and infer severity conservatively using the table below. ### 5. Severity mapping Map Codex findings into the shared 1-10 scale: | Kind | Severity | |------|----------| | Clear correctness/security/data-loss issue | 8-10 | | Strong functional or architectural concern | 6-7 | | Moderate maintainability/test gap | 4-5 | | Minor polish or low-confidence concern | 1-3 | Do not inflate severity just because Codex sounded confident. ## Output Format ### If review succeeded ```markdown # Codex Review Report ## Status COMPLETED ## Findings ### [Short title] **Severity:** N **Location:** path/to/file:line **Description:** What Codex flagged and why it matters. ``` ### If blocked or unsupported ```markdown # Codex Review Report ## Status BLOCKED ## Reason CODEX_NETWORK_BLOCKED ## Notes Short factual explanation of what failed, citing the evidence you observed (`codex.exit` contents, the tail of `codex-events.jsonl`, or `pgrep` output). ``` For a budget expiry specifically, preserve the workspace so the run can be recovered: ```markdown # Codex Review Report ## Status BLOCKED ## Reason CODEX_STILL_RUNNING ## Notes Codex had not written `codex.exit` when the CODEX_REVIEW_TIMEOUT budget expired. Workspace preserved at /tmp/codex-reviewer.XXXXXX for inspection. ``` or ```markdown # Codex Review Report ## Status SKIPPED_UNSUPPORTED_SCOPE ## Notes `--scope=all` is not compatible with this skill's scoped-diff review pass. ``` ## What NOT To Do - Do not review the main workspace directly if that would broaden scope beyond the requested diff - Do not turn this into a whole-repo audit - Do not fix code - Do not suggest fixes - Do not hide Codex infrastructure failures - Do not fail the overall verify run just because Codex was unavailable - **Do not claim Codex finished without having read `codex.exit`.** Writing "Codex completed" or "Codex exited cleanly" in your own message does not make it true, and on the next turn you will read it back as if it were evidence. - **Do not treat a `Monitor` start acknowledgement as a completion event.** "Monitor started … You will be notified" means the wait has *begun*. - **Do not `rm -rf` the temp workspace before `codex.exit` exists** — that kills a running review. - **Do not use `ps aux | grep` to check liveness** — it is broken in this shell. Use `pgrep -f`.