Claude Code × Codex Review setup guide

I put this setup together after hitting a boring but expensive problem: Claude Code can move fast, but I still wanted a second reviewer that was not allowed to edit the repo. Codex is a good fit for that job. After this setup, Claude Code can ask Codex to review a diff, a commit, a pull request, or an OpenSpec change without giving Codex write access.

The setup gives you three useful pieces:

Manual review dispatch: ask Claude Code to “use Codex to review this diff”.
A dedicated codex-reviewer subagent: read-only tools plus the Codex MCP tools, so the review stays clean.
Optional OpenSpec verify hook: after /opsx:verify or /openspec-verify-change, Claude Code can automatically request a Codex second opinion.

When this is useful

Code review before merging a change.
OpenSpec artifact review: proposal, design, spec, tasks, and implementation alignment.
Two-agent development: Claude Code implements; Codex reviews; a human resolves disagreements.

Requirements

Claude Code with the claude command available.
macOS. Other platforms can work, but the Codex CLI path will differ.
Python 3.
Codex CLI.

Install Codex

Recommended: Codex Desktop

If your company uses EDR or antivirus tooling, use the desktop app. The npm package is an unsigned Node script and is commonly blocked by corporate security software.

Download Codex Desktop from:

https://chatgpt.com/codex

Install it to:

/Applications/Codex.app

The bundled CLI lives at:

/Applications/Codex.app/Contents/Resources/codex

It is signed by OpenAI and works better in managed macOS environments.

Alternative: npm install

Use this only if your environment does not block unsigned Node tooling:

npm i -g @openai/codex

If you use npm, replace /Applications/Codex.app/Contents/Resources/codex with codex in the commands below.

Log in to Codex

Open Codex.app once and sign in, or configure Codex with an API key. Then verify the CLI:

echo 'hi' | /Applications/Codex.app/Contents/Resources/codex exec --sandbox read-only -C /tmp -

If it returns a normal response, the CLI is ready.

Step 1: Register Codex as a Claude Code MCP server

claude mcp add -s user codex /Applications/Codex.app/Contents/Resources/codex mcp-server

-s user keeps the configuration local to your user account. It does not modify the project repository.

Verify the connection:

claude mcp list | grep codex
# expected: codex: /Applications/Codex.app/Contents/Resources/codex mcp-server - ✓ Connected

If it shows failed, check the Codex CLI path and make sure Codex is logged in.

Step 2: Create the `codex-reviewer` subagent

mkdir -p ~/.claude/agents

Create this file:

~/.claude/agents/codex-reviewer.md

Paste this content:

---
name: codex-reviewer
description: Use Codex as an independent second reviewer. Use for code review, diffs, files, PRs, and OpenSpec artifacts such as proposal/design/spec/tasks. Trigger when the user asks for review, second opinion, audit, or issue finding on code or spec documents.
tools: mcp__codex__codex, mcp__codex__codex-reply, Read, Bash, Glob, Grep
model: sonnet
---

You coordinate Codex review. Codex performs the real review through MCP tools. Your job is to gather inputs, call Codex, and summarize the result.

## Workflow

1. Identify the review target. The main agent usually passes a diff, file list, PR number, OpenSpec change directory, or spec/proposal/design file. If unclear, read 1-2 key files to confirm scope.

2. Gather raw material:
   - Code: `git diff <ref>...HEAD`, relevant source files, interface definitions, callers, and constraints such as CLAUDE.md.
   - OpenSpec: proposal.md, design.md, specs/*/spec.md, tasks.md.

3. Call Codex with `mcp__codex__codex`. Required settings:
   - `sandbox`: `"read-only"`
   - `approval-policy`: `"never"`
   - `cwd`: project root
   - `prompt`: use the templates below.

4. Keep the `threadId`. If follow-up is needed, use `mcp__codex__codex-reply` with the same `threadId`. Ask at most 2-3 follow-ups.

5. Return a compact report to the main agent.

## Rules

- Do not feed the main agent's opinion or conclusion to Codex. Give raw evidence and objective constraints only.
- Do not filter out Codex findings. If you disagree, list the disagreement for the user to decide.
- Do not let Codex write files. `sandbox: read-only` is mandatory.
- You must not call Edit or Write.

## Prompt template: code review

Please independently review this code change for <project/stack>.

[Project constraints]

[Change]

[Review dimensions]

Correctness: logic errors, edge cases, null handling, exception handling
Project rules: check against the constraints above
Data safety: tenant isolation, SQL injection, authorization problems
Maintainability: naming, abstraction, complexity
Tests: whether tests are missing

Output findings in three levels: Critical, Important, Suggestions. Each finding must include file:line, problem, and fix direction. No praise. Only list problems. If a dimension has no issue, write “None”.


## Prompt template: OpenSpec review

Please independently review these OpenSpec change artifacts.

[Change goal] <why/what from proposal.md>

[Artifacts]

proposal.md

## design.md ## spec(s) ## tasks.md

[Review dimensions]

Closure: proposal goals fully covered by specs
Consistency: fields, terms, and flows aligned across proposal/design/spec/tasks
Completeness: exceptions, boundaries, concurrency, rollback
Testability: acceptance criteria objectively verifiable
Task quality: task granularity, dependencies, acceptance checks

Output findings by dimension. Each finding must include location, problem, and fix direction. No praise. Only list problems.


## Output format

Codex Review Report

Target: Codex thread: threadId=<…>

Critical

[file:line] | Fix:

Important

Suggestions

Disagreements

Codex says: <…>; my view: <…> — user should decide

Not covered

```

Keep the report tight. Do not repeat source text.


## Step 3: Optional OpenSpec verify hook

Use this only if you already run OpenSpec verify skills such as `/opsx:verify` or `/openspec-verify-change`.

### Create the hook script

```bash
mkdir -p ~/.claude/hooks

Create:

~/.claude/hooks/opsx-verify-codex-review.py

Paste:

#!/usr/bin/env python3
"""
PostToolUse hook: when Claude Code runs an OpenSpec verify skill,
inject additional context that asks the main agent to run codex-reviewer
as an independent second review.
"""
import json
import sys


def main():
    try:
        data = json.load(sys.stdin)
    except Exception:
        return

    if data.get("tool_name") != "Skill":
        return

    tool_input = data.get("tool_input") or {}
    skill = tool_input.get("skill") or tool_input.get("skill_name") or ""

    targets = {"opsx:verify", "openspec-verify", "openspec-verify-change"}
    if skill not in targets:
        return

    instruction = (
        "[opsx-verify-codex-review hook] verify skill has completed. "
        "Your final response must include an independent Codex review:\n\n"
        "1. First output the verify conclusion.\n"
        "2. Then call the Agent tool with subagent_type=codex-reviewer and ask Codex "
        "to review the same change scope. Include the change path or commit range, "
        "key CLAUDE.md constraints, and files under review.\n"
        "3. Organize the final response as:\n"
        "   ## verify conclusion\n"
        "   ## Codex independent review\n"
        "   ## disagreements, if any — user decides\n\n"
        "Fallback: if codex-reviewer is unavailable, call the Codex CLI directly with Bash:\n"
        "  /Applications/Codex.app/Contents/Resources/codex exec --sandbox read-only "
        "-C <repo-root> -o /tmp/codex-review-output.md \"<full prompt>\"\n"
        "Then read /tmp/codex-review-output.md. Do not use the npm Codex binary in EDR environments.\n\n"
        "Do not pass the verify conclusion to Codex. Codex must form an independent opinion."
    )

    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PostToolUse",
            "additionalContext": instruction,
        }
    }))


if __name__ == "__main__":
    main()

Make it executable:

chmod +x ~/.claude/hooks/opsx-verify-codex-review.py

Register the hook

Edit:

~/.claude/settings.json

Add this under hooks.PostToolUse:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Skill",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /Users/<YOUR_USER>/.claude/hooks/opsx-verify-codex-review.py",
            "timeout": 10,
            "statusMessage": "Checking if opsx:verify → triggering Codex review..."
          }
        ]
      }
    ]
  }
}

Replace <YOUR_USER> with the output of:

whoami

Activate the hook

In Claude Code, run:

/hooks

Open and close the hooks UI. That hot-loads the updated settings.

Verify the setup

MCP connection

claude mcp list | grep codex
# expected: codex: ... mcp-server - ✓ Connected

Hook script test

echo '{"tool_name":"Skill","tool_input":{"skill":"opsx:verify"},"tool_response":{}}' \
  | python3 ~/.claude/hooks/opsx-verify-codex-review.py | python3 -m json.tool
# expected: JSON containing hookSpecificOutput.additionalContext

 echo '{"tool_name":"Skill","tool_input":{"skill":"writing-plans"},"tool_response":{}}' \
  | python3 ~/.claude/hooks/opsx-verify-codex-review.py
# expected: no output

End-to-end test

Open a new Claude Code session inside a Git repository and say:

Use codex-reviewer to review the HEAD commit.

The main agent should dispatch the codex-reviewer subagent. The subagent should call mcp__codex__codex, then return a report with Critical, Important, and Suggestions sections.

Daily usage

Manual reviews

Use Codex to review the current diff.
Ask codex-reviewer to check this PR.
Ask Codex to audit this OpenSpec change.

OpenSpec verify automation

Run your normal verify flow:

/opsx:verify
/openspec-verify-change

After verify completes, Claude Code should add:

## verify conclusion
<verify result>

## Codex independent review
<Codex findings>

## disagreements
<Any conflicts between the two opinions>

Emergency direct Bash call

If MCP and subagents are not available:

/Applications/Codex.app/Contents/Resources/codex exec \
  --sandbox read-only \
  -C /path/to/repo \
  -o /tmp/codex-review.md \
  "Please review commit <SHA>: $(git show <SHA>)"

Troubleshooting

macOS says Codex will damage your computer

Corporate EDR is blocking the unsigned npm Codex binary. Use the signed Codex.app CLI:

/Applications/Codex.app/Contents/Resources/codex

Optionally remove the npm package:

npm uninstall -g @openai/codex

Codex says the model is unsupported

Do not force a model with -m gpt-5-codex. Let Codex use the account default.

MCP or subagent does not appear

Claude Code loads MCP tools and subagents at session start. Restart Claude Code or open a new session after adding them.

Hooks can be hot-loaded with:

/hooks

`which codex` still points to npm

The MCP registration uses an absolute path, so this does not affect MCP. If you want codex in your shell to point to the app binary:

npm uninstall -g @openai/codex
ln -s /Applications/Codex.app/Contents/Resources/codex /opt/homebrew/bin/codex

Hook injected context but no reviewer ran

Check that the subagent file exists:

ls ~/.claude/agents/codex-reviewer.md

If it exists, start a new Claude Code session. If the subagent is still unavailable, the hook fallback can call the Codex CLI directly.

Customization

Change review dimensions

Edit the prompt templates in:

~/.claude/agents/codex-reviewer.md

Add project-specific rules such as naming conventions, security constraints, or performance requirements.

Change which skills trigger the hook