Codex Review

---

name: codex-review description: Enable or disable automatic Codex CLI code review after every code edit. Use when user wants to set up multi-model collaboration where Claude writes code and Codex automatically reviews it for bugs. Trigger phrases: "开启 codex review", "codex 自动审查", "let codex review my code". argument-hint: "[on|off|status|test]" disable-model-invocation: true

Manage a Stop hook that calls local Codex CLI once after each Claude agentic loop turn.

Flow when enabled:

Claude session starts
  → First Stop: Hook initializes a Codex session
      Codex reads CLAUDE.md + project structure (builds context)
      Thread ID saved to /tmp/codex-review-thread-<CLAUDE_SESSION_ID>.txt

Claude agentic loop runs (may edit many files)
  ↓  while(true) { think → tool calls → observe }
  ↓  loop ends, Claude hands control back to user
  → Stop Hook fires ONCE (deterministic, after full turn)
  → scripts/review.sh collects ALL changed files via git diff HEAD
  → Codex reviews the complete turn diff with project knowledge
  → If Codex finds issues, the Stop hook returns JSON decision=block
  → Claude sees the block reason and continues fixing
  → Loop until Codex reports no issues

Claude session ends → next session creates a fresh Codex session

Instructions

Parse $ARGUMENTS and handle the following cases.

---

Case 1: $ARGUMENTS is "on" or "enable"

1. Run which codex to check if Codex CLI is installed.

   • If not found, stop and tell the user:

     ❌ Codex CLI not found.
     Install: npm i -g @openai/codex
     Authenticate: codex login  (requires ChatGPT Pro/Business)
     

2. Read .claude/settings.local.json. If the file does not exist, treat its content as {}.

3. Merge the following into the JSON, preserving all existing keys (especially permissions):

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/skills/codex-review/scripts/review.sh"
          }
        ]
      }
    ]
  }
}

If a Stop array already exists, append this entry rather than replacing the array. If an entry whose command contains codex-review already exists, do not add a duplicate.

4. Write the merged result back to .claude/settings.local.json.

5. Confirm to the user:

   ✅ Codex auto-review enabled
   Watches: .java / .ts / .tsx / .js / .py (test files excluded)
   Trigger: once per turn, after Claude's agentic loop ends (Stop event)
   Disable anytime: /codex-review off
   

---

Case 2: $ARGUMENTS is "off" or "disable"

1. Read .claude/settings.local.json.
2. Remove from hooks.Stop the entry whose command contains codex-review.
3. If hooks.Stop becomes an empty array, delete that key. If hooks becomes empty, delete that key too.
4. Write back.
5. Clean up any lingering Codex session files: rm -f /tmp/codex-review-thread-*.txt /tmp/codex-review-thread-*.txt.lock
6. Confirm:

   ⛔ Codex auto-review disabled
   Codex session files cleaned up.
   

---

Case 3: $ARGUMENTS is "status" or empty

1. Read .claude/settings.local.json.

2. Check whether a Stop entry whose command contains codex-review exists → hook enabled/disabled.

3. Run which codex → installed/not installed.

4. Report a status table:

   Hook:      enabled / disabled
   Codex CLI: installed (path) / not installed
   Watches:   *.java *.ts *.tsx *.js *.py (excl. test/spec)
   Config:    .claude/settings.local.json
   

---

Case 4: $ARGUMENTS is "test"

1. Verify codex is available via which codex.
2. Run a smoke test by piping a buggy snippet to Codex:

   echo 'Review this for bugs: def divide(a, b): return a / b' | \
     codex exec --json --sandbox read-only --skip-git-repo-check -
   

3. Show the output and confirm whether the integration works end-to-end.

---

Notes

• Config lives in .claude/settings.local.json — project-scoped, should be gitignored.
• Hook script: .claude/skills/codex-review/scripts/review.sh — must be executable (chmod +x).
• Hook event is Stop — fires once per turn when Claude finishes its agentic loop.
• Script guards with git diff HEAD: if no code files changed, exits immediately without calling Codex.
• Excluded file patterns: *test*, *Test*, *spec*, *__tests__*.
• Session persistence: Codex thread ID stored in /tmp/codex-review-thread-<CLAUDE_SESSION_ID>.txt. Each Claude session gets its own Codex session; sessions are isolated across Claude restarts.
• First Stop with code changes: Codex bootstraps by reading CLAUDE.md and project structure.
• Subsequent turns: Codex resumes the same session and reviews only the git diff HEAD of that turn.
• If Codex session expires mid-session, the script auto-clears the session file and falls back to a stateless review for that turn.
• Codex "no issues" results exit quietly. Findings are returned as a Stop hook JSON block reason so Claude can continue fixing.
• Codex runs with a read-only sandbox for new/stateless sessions instead of bypassing approvals and sandboxing.
• Requires: codex CLI installed and codex login completed (ChatGPT Pro/Business account).