codex-code-review

Get an independent code review from OpenAI's Codex CLI using GPT-6.1-Sol at extra-high reasoning effort. Codex acts as a principal engineer providing a second opinion. You have more context than Codex — use your own judgment to decide what feedback to incorporate.

Invoking Codex

Use codex exec to run a one-shot review. Always write output to a temp file for reliable capture.

Important: Each step below must be a separate Bash tool call. Do NOT use $() command substitution or combine steps into one command — this triggers permission prompts.

Step 1 — Create a temp file:

mktemp /tmp/codex-review.XXXXXXXX

This prints the created file path. Save this path for use in steps 2 and 3.

Step 2 — Run Codex in the background (use the literal path printed by step 1):

codex exec \
  -m gpt-6.1-sol \
  -c 'model_reasoning_effort="xhigh"' \
  --ephemeral \
  -s read-only \
  -o <TMPFILE> \
  "$PROMPT" < /dev/null \
  2> <TMPFILE>.err.log

Critical — close stdin: The < /dev/null redirect is required. Without it, codex may block waiting for stdin input when run as a background job, and the task will hang indefinitely instead of completing.

Critical — run in background: You MUST set run_in_background: true on this Bash tool call. Codex with xhigh reasoning regularly takes 3-8 minutes. If you run it in the foreground, the Bash tool will time out after 2 minutes and return partial/empty output — you will then incorrectly interpret incomplete results as the final review. Running in the background ensures you receive an explicit completion notification. Do NOT read the temp file, check on progress, or take any action on the review until you receive the background completion notification. Tell the user that Codex is running and you'll report back when it finishes.

Step 3 — Read and clean up (only after background completion): After receiving the background task completion notification, use the Read tool to read the temp file, then delete both files with rm <TMPFILE> <TMPFILE>.err.log — unless you may resume the session, in which case keep the .err.log until the last round is done.

Do NOT read <TMPFILE>.err.log whole — it holds the banner plus the full transcript. grep it: for ERROR when a run looks wrong, for session id: when you plan to resume. The review itself always comes from <TMPFILE>.

In steps 2 and 3, replace <TMPFILE> with the actual path printed by step 1.

Flags explained:

• 2> <TMPFILE>.err.log — capture stderr. It carries the banner (model, sandbox, effort, session id), any ERROR lines, and the transcript. This is the only channel that reports a failed run, and the only place the session id appears.
• -m gpt-6.1-sol — model selection (the default for reviews). Pinned, so a /model switch in the Codex app can't silently change what runs.
• -c 'model_reasoning_effort="xhigh"' — deep thinking, principal-engineer level. Sol also accepts max and ultra above this; xhigh is the sweet spot for review latency. Avoid ultra — it auto-delegates subtasks.
• --ephemeral — no conversation persistence, clean context. Drop it if another round is likely: an ephemeral session is not persisted, so its id cannot be resumed even though the banner still prints one.

Do NOT add --json (prints the event stream as JSONL on stdout). It looks like a tidier way to get the session id, but it moves errors off stderr into {"type":"error",...} events on stdout and leaves stderr empty — a failed run then looks clean. It also suppresses the banner, taking the session id with it. stderr carries both; --json costs the error channel and buys nothing.

• -s read-only — read-only sandbox, prevents Codex from modifying any files
• -o <TMPFILE> — write output to file (avoids noisy stdout metadata)

Model and reasoning effort are defaults, not a lock. If the user asks for a different model or a different reasoning effort, run what they asked for — pass it through -m / -c 'model_reasoning_effort="..."'. The values above are what you pick when the user hasn't expressed a preference.

Optional invocation choices

Keep these out of the default command. Follow each option's conditions before using it.

Faster service tier

Add this flag to an initial or resumed invocation only when the user explicitly asks for the fast service tier or faster Codex execution:

-c 'service_tier="fast"'

The fast service tier is more expensive. Never enable it on your own initiative. Do not infer it from urgency, task complexity, or a general request to finish quickly.

The ask does not carry forward. It authorizes the one invocation the user asked for, and nothing else — not the next review, not a resumed round of the same review, not a re-run after a failure. Every fast-tier run needs its own explicit request from the user. An earlier "use fast" in this conversation is not permission for a later run.

Online research and network access

Web search already works in the default -s read-only review: it runs server-side, outside the sandbox, and is on by default in current Codex (0.164+). For reviews that hinge on current external facts — library/API behavior, deprecations, CVEs — just tell Codex in the prompt to use web search to verify them. No flag change needed; add -c tools.web_search=true only to pin it on explicitly.

Shell network access (curl, npm view, pip index versions) is off under -s read-only. When a review needs it, replace -s read-only with a permission profile that extends the built-in read-only profile and turns network on — writes stay blocked by the sandbox:

-c 'default_permissions="review"' \
-c 'permissions.review.extends=":read-only"' \
-c 'permissions.review.network.enabled=true'

Drop -s read-only when using these — sandbox_mode and default_permissions can't both be set. The same three flags work on resume, replacing -c 'sandbox_mode="read-only"'. Confirm it took effect: the stderr banner should read sandbox: read-only (network access enabled).

Don't use -c sandbox_workspace_write.network_access=true here: it only applies to workspace-write and is silently ignored under read-only — the banner shows plain read-only and fetches fail with a DNS error. And don't switch to workspace-write to get network; that lets Codex modify the repo.

Enable network only when the review needs shell commands to fetch — not for research, which web search already covers.

Continue the review session

Use a persisted session when the calling agent expects another round of feedback or iteration:

1. Omit --ephemeral from the initial invocation. This is required; ephemeral sessions cannot be resumed.

2. Get the session id from the initial run's stderr banner:

   grep 'session id:' <TMPFILE>.err.log

   which prints:

   session id: 019ff382-15da-7b32-847f-5a47fa75523d

   Keep that UUID, and don't delete <TMPFILE>.err.log until you're done resuming.

3. After assessing or applying the first review, create a new temp output file with the Step 1 mktemp command.
4. Run the follow-up in the background from the same repository:

codex exec resume <SESSION_ID> \
  -m gpt-6.1-sol \
  -c 'model_reasoning_effort="xhigh"' \
  -c 'sandbox_mode="read-only"' \
  -o <NEW_TMPFILE> \
  "$FOLLOWUP_PROMPT" < /dev/null \
  2> <NEW_TMPFILE>.err.log

Don't use --last. It resumes the newest persisted session for the working directory, which is not necessarily yours — another Codex instance, a ChatGPT app, or a second agent working in the same repo may have started a session after yours, and --last will silently hand your follow-up prompt to it. Always resume by explicit session id. If you don't have one — stderr was discarded, say — start a fresh review rather than guessing with --last.

The resumed round prints its own banner, so grep its stderr file the same way if another round follows. Apply the same background-run, completion-notification, output-reading, cleanup, and error-handling rules to every resumed round. Add -c 'service_tier="fast"' only if the user explicitly asked for the fast tier for this particular run — a fast-tier initial review does not authorize a fast-tier follow-up.

Critical — temp file creation: On macOS, mktemp only replaces the X's when they are the last characters of the template. Do NOT add a file extension (e.g., .md) after the X's — this causes mktemp to use the template literally without substitution. The template /tmp/codex-review.XXXXXXXX (no extension) is correct and must be used verbatim.

Error handling: If codex returns a non-zero exit code, read stderr for the error message. Report the error to the user and do not retry automatically — there may be an auth or config issue the user needs to resolve.

Telling Codex what to review

Codex has shell access — it can run git commands and read files itself. Don't bloat the prompt by embedding diffs or file contents. Instead, tell Codex what to do in the prompt and let it retrieve the code.

Git diff (most common — review uncommitted changes)

Tell Codex to run git diff (or git diff --cached for staged changes).

Git commit(s)

Tell Codex the commit hash(es) and to run git show <hash> or git log -p <hash1>..<hash2>.

Specific files or directory

Tell Codex the file paths or directory to review and to read them itself.

Scoping the review

To narrow what Codex reviews, pass the scope in the prompt itself. For example:

• "Run git diff -- src/api/routes.py src/api/middleware.py and review those changes"
• "Read the files in src/auth/ and review them"
• "Run git show abc1234 -- lib/ and review only the lib changes"

Codex handles the filtering — no need to embed content.

Important:

• Always tell Codex it can run git commands if it needs more context beyond what you asked it to review.
• Always tell Codex to return an error message (not silently fail) if it cannot access something.

Constructing the prompt

The prompt to Codex must include these sections:

1. Context summary (required)

A brief summary of what the code changes are for and the goal. This prevents Codex from optimizing for the wrong thing.

2. What to review (required)

Tell Codex what to review — a git command to run, file paths to read, or (rarely) embedded code.

3. Focus areas (optional but recommended)

If you or the user have specific concerns, list them. Examples: "pay special attention to error handling", "check for SQL injection", "verify the caching logic is correct".

4. Output format instructions (required)

Tell Codex exactly how to structure its response:

Return your review as plain text in this format:

CRITICAL ISSUES
Issues that must be fixed — bugs, security vulnerabilities, data loss risks.
List each with: file, line/section, issue description, and what should change.
If none, write "None found."

IMPROVEMENTS
Code quality, performance, readability, or maintainability suggestions.
Tag each with a severity: [high] (real impact on correctness, performance, or security if left), [medium] (meaningful quality improvement), [low] (nitpick or style preference).
List each with: severity tag, file, line/section, what to improve, and why.

Be token-efficient. Use whichever is most concise: a brief description, a function/variable name, a short code snippet, or a one-liner fix. Don't rewrite large blocks of code — describe the change instead.

POSITIVE NOTES
Things done well that should be kept.

SUMMARY
2-3 sentence overall assessment.

Do NOT include metadata, conversation artifacts, or commentary outside this format.
If you cannot access a file or run a command, say so clearly in your response instead of silently skipping it.

Example full prompt

You are reviewing code changes in a git repository. Here is the context:

**Goal:** Adding rate limiting middleware to the Express API to prevent abuse of the /api/search endpoint.

**Focus areas:** Check that the rate limit configuration is correct, that the middleware ordering is right, and that error responses follow our existing API format.

You have access to git and the filesystem. If you need more context, run git commands to explore. If you cannot access something, say so clearly.

**What to review:** Run `git diff` to see the uncommitted changes, then review them.

Return your review as plain text in this format:
[... format instructions from above ...]

Processing Codex's response

1. Read and assess the feedback yourself

Do NOT blindly apply Codex's suggestions. You have far more context about:

• The broader codebase and its conventions
• The user's intent and constraints
• What has already been tried or discussed
• Project-specific patterns and trade-offs

For each piece of feedback, decide:

• Incorporate — the feedback is correct and valuable
• Adapt — the spirit is right but the specific suggestion needs adjustment for this codebase
• Discard — the feedback is wrong, irrelevant, or conflicts with known constraints

2. Fix what you can

If Codex identified real issues that you agree with and can fix, fix them before reporting to the user. Don't make the user do work you can handle.

3. Report to the user

Present a clear summary structured as:

Codex Review Summary:

• Brief overview of what Codex found

My Assessment:

• Which feedback points you're incorporating and why
• Which you're discarding and why
• Any points you're unsure about and want the user's input on

Changes Made:

• What you fixed based on the review
• Why those changes improve the code

For Your Decision:

• Any feedback points that require the user's judgment (e.g., architectural trade-offs, business logic questions)

4. If Codex returns errors

If Codex couldn't complete the review (auth issues, timeout, can't access files):

• Report the error clearly to the user
• Do NOT retry automatically
• Suggest what the user might check (codex auth, file permissions, etc.)

What NOT to do

• Do not treat Codex's feedback as authoritative. It is a second pair of eyes, not the final word.
• Do not call Codex repeatedly in a loop trying to get different answers.
• Do not send the entire repository — keep reviews focused on the relevant changes.
• Do not skip your own assessment. The user is relying on your judgment to filter and contextualize Codex's raw feedback.