Codex PR Review

Local Codex PR review

One command does everything. Run it in the background and wait for it; do not re-verify the Codex binary, the scripts, the token minter or the gh login first. The script fails loudly if anything is missing.

nohup scripts/codex-review/codex-pr-review.sh <repo-dir> <pr-number> [extra-prompt-file] > <log> 2>&1 &

Then wait on the log (until grep -q 'codex-pr-review: done\|FAILED' <log>; do sleep 15; done) and keep working. Every exit path prints exactly one of those markers, including preflight failures. A run normally takes 5-20 minutes. The watchdog kills an attempt, with every process it spawned, after 8 minutes without an event from the Codex process, or 30 minutes total, and retries once unless the verdict was already posted. Never launch a bare codex exec for a review.

What the script does

• Fetches the PR head into the sibling worktree <repo-dir>-pr-<n>, so the main checkout is never touched. If GitHub has not advertised the PR's Git pull ref yet, it fetches the exact head from the PR API and rechecks that head before starting the review. It never substitutes a moving branch tip. The tool marks worktrees it created with a <repo-dir>-pr-<n>.codex-review-owned sentinel; on reruns it resets and cleans only those (ignored files such as node_modules are kept) and refuses a path at that location it did not create. A per-PR lock refuses a second concurrent run; a lock whose owner is dead is reclaimed through a short-lived <lock>.reclaim mutex, so two reclaimers cannot clobber each other. Cancelling the script (Ctrl-C, SIGTERM) stops the runner and every process of the attempt before the lock is released; the runner pid is kept in the lock so a runner that outlives a hard-killed wrapper still counts as live. A worktree created by an earlier version of the script has no sentinel: add the file by hand (any content) or remove the worktree with git worktree remove.
• Chooses the posting account. GitHub refuses a formal review from the PR author, so a PR authored by the logged-in gh user posts through a mentra-release-coordinator GitHub App token minted by mentra-release-coordinator-token.mjs; anyone else's PR posts from the logged-in account. Override with GH_ACCOUNT=app|own.
• Writes the standard prompt: read the diff against the base, read every existing comment (bots included) and judge each on its merits, favour low complexity and a coherent design over patchy fixes, no edits or pushes, and finish with gh pr review <n> --approve or --request-changes whose body starts with Reviewed by local Codex (gpt-6.1-sol, medium). and lists what was checked. If GitHub refuses the formal review it falls back to --comment with Approve. or Request changes. as the first line.
• Always adds an "Is this change needed?" step: Codex must judge whether the change is needed or desirable for the project at all (real problem, existing or planned alternative, surface area and maintenance cost versus benefit, smaller change possible) and let that weigh in the verdict, not only implementation quality.
• Runs codex-review.sh (watchdog + one retry) and prints Codex's final message. The runner starts codex exec --json by default, or the small stdio app-server adapter for a configured desktop project. Both use their own server event stream as the heartbeat, so other Codex sessions on the machine can never be mistaken for this one; every process of the attempt carries a unique CODEX_REVIEW_ATTEMPT marker so it can be terminated even if Codex exits first. Success means a review carrying the marker was found on the head commit after the run started, checked through the GitHub API by review-receipt.sh; the runner performs the same check before any retry so a verdict posted just before a crash is never duplicated. Artifacts: $CODEX_REVIEW_HOME/<repo>-pr-<n>-<timestamp>/{prompt.txt,last-message.txt,runner.log,events-<attempt>.jsonl} (default ~/.codex-reviews).

Configuration

Use a desktop Review project

On the host that runs reviews, create a folder and add it as a local Codex project named Review. Save its absolute path once:

mkdir -p "$HOME/dev/Codex-Reviews" "${CODEX_REVIEW_HOME:-$HOME/.codex-reviews}"
printf '%s\n' "$HOME/dev/Codex-Reviews" > "${CODEX_REVIEW_HOME:-$HOME/.codex-reviews}/project-directory"

Future skill invocations use codex app-server --stdio and the documented initialize → thread/start → turn/start protocol, with that folder as the saved session's starting directory. The server creates a persistent interactive session and the adapter gives it a <repo> #<PR> · review title. This matters: codex exec has a separate session source that default history lists exclude; changing its cwd alone does not establish desktop visibility. --thread-source is an analytics label and does not change that history source.

The reviewer receives the separate PR worktree path for all code inspection and tests; worktree ownership, locks, watchdogs and verdict checks still apply. Existing sessions are not moved. This is configured per host: a Mini review needs the folder registered as a project on the Mini's connection. Do not use --ephemeral or a separate CODEX_HOME, which would hide sessions from the usual desktop account.

For durable project assignment, initialize the same host's codex app-server --stdio and call its documented project/list method. Follow pagination and match the project's roots[].path to the exact configured directory. Save that returned ID in $CODEX_REVIEW_HOME/project-id (default ~/.codex-reviews/project-id) or set CODEX_REVIEW_PROJECT_ID. Desktop-tool list_projects IDs can use a different namespace: do not copy those IDs into this configuration. The adapter passes the app-server ID as thread/start.projectId and verifies the response. It never reads or edits Codex's database. Without an ID, grouping depends on the registered folder; verify visibility on the next actual review rather than creating a duplicate review as a probe.

Override the saved path with CODEX_REVIEW_PROJECT_DIR=/absolute/path, or set it to an empty string for one invocation to start in the PR worktree instead. Without a saved path or override, the existing exec behavior is unchanged. A configured missing directory is an error, so reviews cannot silently appear somewhere else. An explicit directory override ignores the saved project ID; also pass CODEX_REVIEW_PROJECT_ID if that different folder needs a durable assignment. Project reviews require Node.js and a Codex version supporting the app-server protocol. Incompatible protocol, failed/interrupted turns and missing final text fail the attempt; they never produce a successful review merely from progress.