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
/plugin marketplace add Sateezg/codex-bridge
/plugin install codex-bridge@codex-bridgeWhat 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-bridge2Manually: put the files in place
.claude/agents/codex-reviewer.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/codex-reviewer.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/codex-reviewer.mdCursor also reads .claude/agents/
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