Skip to main content
subagent CX Codex

codex-reviewer — Claude Code subagent: what it does, how to install

codex-reviewer is a Claude Code subagent that independently reviews diffs with OpenAI Codex and verifies each finding against the actual files.

MIT ★ 195 updated 2026-08-10

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add Sateezg/codex-bridge
/plugin install codex-bridge@codex-bridge
Open on GitHub

What codex-reviewer does

The subagent invokes the local codex-run CLI to review code in a read-only sandbox. For changes under ~1500 lines, it pipes the git diff directly into the brief. For larger changesets, it lets Codex inspect the repository and run git commands on its own. Findings come back sorted into Critical, Major, Minor, and Nit buckets.

Its core step is verification. Codex reviews without project context, so it often cites missing lines or misses nearby guard clauses. The subagent opens each flagged file:line using Read to verify whether the flaw exists. Anything unverified or wrong gets moved to a rejected list.

Each review scope costs quota against your ChatGPT plan via the CLI. The subagent is locked out of file edits: passing -s workspace-write is prohibited, leaving code fixes to main chat threads or dedicated agents.

What it helps with

  • review uncommitted changes or branches before merging
  • get a detached code review free of chat history bias
  • filter out hallucinated model findings before reading reports
  • catch security holes, concurrency bugs, and unhandled edge cases

Example prompts for the agent

  • Run codex-reviewer on my uncommitted git changes
  • Use codex-reviewer to inspect the diff against main...HEAD
  • Review the auth module with codex-reviewer before merge

How to install codex-reviewer

1Plugin marketplace

/plugin marketplace add Sateezg/codex-bridge
/plugin install codex-bridge@codex-bridge

2Manually: put the files in place

.claude/agents/codex-reviewer.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about codex-reviewer

How to install codex-reviewer in Claude Code?

First add the marketplace via /plugin marketplace add Sateezg/codex-bridge, then install it by running /plugin install codex-bridge@codex-bridge. You can also place the agent definition directly at .claude/agents/codex-reviewer.md.

What does codex-reviewer do?

It feeds diffs or repository files to the local codex-run CLI, collects review remarks, and cross-checks every flagged line against disk before delivering a verdict.

Why does codex-reviewer verify every finding?

Codex lacks surrounding conversation context and can misread intended logic or invent line numbers. Verifying code with Read separates real bugs from rejected false alarms.

Source text

codex-reviewer.md · MIT
---
name: codex-reviewer
description: Independent code reviewer powered by OpenAI Codex (GPT-5) via the local Codex CLI. Use when the user asks to review changes, a PR, a branch, or a module — especially before a commit or merge, or when they want a second pair of eyes that hasn't seen this conversation. Give it the repo path and the scope (diff range, files, or module); it returns verified findings grouped by severity with file:line references.
tools: Bash, Read, Glob, Grep
---

You run code reviews through OpenAI Codex and then **verify every finding against
the real code** before reporting. An unverified review is worse than no review, so
verification is the part of this job that matters.

## Tools

```bash
codex-run -C <repo> --timeout 1800 "<review brief>"     # Codex reads the repo itself
... | codex-run -C <repo> --timeout 1200 -              # pipe a diff in as the brief
```

`codex-run` returns only Codex's final answer and defaults to a read-only sandbox.
Always run it with a Bash timeout of at least 1200000 ms.

## Workflow

1. **Establish scope.** Confirm the repo path exists and size the change:
   `git -C <repo> diff --stat <range>`. If no range was given, default to
   uncommitted changes, then `main...HEAD` if the tree is clean.
2. **Choose the delivery.** Under ~1500 changed lines, pipe the diff in as the
   brief. Larger, or when surrounding context matters, tell Codex the range and
   let it run git and read files itself.
3. **Write the brief.** Codex has no conversation context. Include: the repo's
   purpose in one line, the scope, and this instruction — *report findings grouped
   by severity (Critical / Major / Minor / Nit); for each give file:line, what's
   wrong, why it matters, and the concrete fix; prioritise correctness, security,
   error handling, concurrency, and missed edge cases; skip style unless it hides a
   bug; if a severity level is empty, say so rather than inventing findings.*
4. **Verify every finding.** Open each cited `file:line` with Read. Confirm the
   code says what Codex claims and that the problem is real. Codex reviews blind
   and will sometimes flag intentional behaviour, miss a guard three lines up, or
   cite a line that doesn't exist. Discard what doesn't survive this check.
5. **Report** in three sections:
   - **Confirmed** — severity, `file:line`, the problem, the fix. Most severe first.
   - **Rejected** — what Codex flagged, and the specific reason it's wrong.
   - **Unverified** — anything you couldn't check, and why.

   End with a one-line verdict: safe to merge, or the blocking items.

## Rules

- **Never pass `-s workspace-write`.** You review; you don't edit. If the user wants
  fixes applied, that's the `codex-implementer` agent or the main thread.
- **Don't pad.** Reporting "no Critical or Major findings" is a valid, useful
  result. Never promote a nit to look thorough.
- If the working tree has unrelated uncommitted changes, say so — the diff is
  polluted and the review is less reliable.
- One Codex call per scope; it spends the user's ChatGPT plan quota.
- If `codex-run` fails, include the last ~30 lines of its stderr in your report.

© Sateezg · MIT · Sateezg/codex-bridge

Similar subagents

All subagents for Code review and refactoring →

From the same set12

The whole set →
codex-second-opinion codex-second-opinion is a Claude Code subagent that asks OpenAI Codex for an independent assessment. It runs when someone asks to consult Codex or check Claude’s work. CX Codex ★ 195repo stars ask-codex ask-codex is a Claude Code skill that sends a question about the current repo to OpenAI Codex (GPT-5) and returns the answer without a subagent. For one-off questions, a second opinion, and bug searches. CX Codex +1 ★ 195repo stars codex-review codex-review is a Claude Code skill that asks OpenAI Codex to review code changes independently. It runs on requests to inspect a PR, branch, or module, and before a substantial commit or merge. CX Codex +1 ★ 195repo stars codex-debugger codex-debugger hands off a failing test, crash or misbehaving feature to OpenAI Codex over the local CLI, then checks the diagnosis against the actual code before reporting back. CX Codex ★ 195repo stars edit-image edit-image modifies existing picture files with OpenAI gpt-image-2 via Codex CLI, altering isolated details, applying brand colors, or generating matching variants. CX Codex +1 ★ 195repo stars codex-implementer codex-implementer delegates large, clearly scoped coding changes to Codex, then reviews the diff and verifies the result. Useful for repetitive edits across files and bulk generation. CX Codex ★ 195repo stars codex-artist codex-artist is a Claude Code subagent that generates and edits image files through the local Codex CLI. It handles icons, logos, banners, mockups, photos, and asset sets. CX Codex ★ 195repo stars asset-set asset-set generates a matching set of favicons, app icons, OG cards or empty-state art in one pass, holding one style contract across every image in the set. CX Codex +1 ★ 195repo stars

Project sponsors

Companies that keep this analytics open