openai-reviewer
Skill23 starsChanged 13 days agoMITView on GitHub
Run OpenAI Codex CLI as the code reviewer; Claude writes, Codex reviews, never self-review. Invoke for ALL review requests ("review", "check it", "look it over", "code review") and after any non-trivial code. The Stop hook also calls it.
In this repository45 other files it gives its agents.
- AGENTS.mdAGENTS.md
- dependency-analyzerSkill
- docsSkill
- handoffSkill
- plugin-homeSkill
- schema-validatorSkill
- security-auditSkill
- session-auditSkill
- test-validatorSkill
- claude-codeSkill
- codexSkill
- opencodeSkill
- chartsSkill
- export-csvSkill
- export-excelSkill
- make-chartSkill
- make-html-reportSkill
- make-pdfSkill
- a2a-communicateSkill
- a2a-handle-inboundSkill
- codebase-inspectionSkill
- ethos-skill-authoringSkill
- native-mcpSkill
- github-authSkill
- github-code-reviewSkill
- github-issuesSkill
- github-pr-workflowSkill
- github-repo-managementSkill
- birth-ritualSkill
- get-to-know-youSkill
- xurlSkill
- arxivSkill
- grounded-citationsSkill
- research-paper-writingSkill
- reddit-researchSkill
- code-reviewSkill
- coding-agentSkill
- planSkill
- requesting-code-reviewSkill
- spikeSkill
- subagent-driven-developmentSkill
- systematic-debuggingSkill
- tddSkill
- writing-plansSkill
- no-ai-slopSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 11
All reviews go through this skill: When the user asks for any kind of review — explicit ("review this", "code review") or implicit ("check …
- Distinctive: line 16
Before calling Codex, scan your own diff for things you would have caught yourself:
- Very specific: line 51
Add --focus <security|performance|correctness|style|test> to narrow scope.
- Very specific: line 63
Project rules in
CLAUDE.mdtake precedence over Codex: If Codex demands an ethos-violating change (error handling for impossible …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
OpenAI Code Review
Routing rule (hard)
All reviews go through this skill. When the user asks for any kind of review — explicit ("review this", "code review") or implicit ("check it", "look it over") — go through the two-pass flow below.
Two-pass review flow
Pass 1 — Self-review (Claude, fast): Before calling Codex, scan your own diff for things you would have caught yourself:
- Typos, dead code, unused imports/variables
- Lint and typecheck violations (run
pnpm lint/pnpm typecheckif changes are non-trivial) - Ethos rule violations: error handling for impossible cases, abstractions for single-use code, speculative flexibility, comments restating what the code does
- Tests missing for new behavior
Fix everything you find. Only then move to Pass 2.
Pass 2 — Codex review (architectural, 5-year horizon):
Invoke openai-review. Codex looks for what you cannot easily see in your own work: brittle abstractions, hidden coupling, API choices that will be hard to evolve, premature flexibility, things that rot under scale or team turnover.
The split exists because LLM self-review is unreliable for the things you wrote yourself. Pass 1 catches mechanical issues; Pass 2 brings an outside perspective.
Style
Reviews run in the voice of Linus Torvalds, focused on what will break in 5 years:
- Brittle abstractions and architectural foot-guns
- Hidden coupling that surprises future maintainers
- API choices that will be hard to evolve
- "Cleverness" that obscures intent
- Premature flexibility / speculative generality
The script bakes this framing into every Codex call.
Modes
openai-review defaults to uncommitted if no mode is given.
| Mode | When to use |
uncommitted | Active coding — staged + unstaged changes (default) |
last-commit | Review the latest commit only |
against-main | Whole branch + uncommitted vs. main |
against-origin | Unpushed commits vs. origin |
Add --focus <security|performance|correctness|style|test> to narrow scope.
Acting on findings
Codex returns JSON. Apply judgment — not every finding is correct.
| Severity | Action |
critical, high | Fix |
medium | Judgment call — fix unless it conflicts with project rules |
low | Usually skip; surface to user only if relevant |
Project rules in CLAUDE.md take precedence over Codex. If Codex demands an ethos-violating change (error handling for impossible scenarios, abstractions for single-use code, speculative flexibility), ignore it and explain why in one line.
Auto-loop (Stop hook)
A Stop hook runs openai-review against-main after every code-writing turn:
- Approved (no critical/high) → turn ends cleanly
- Issues + iteration < 2 → review fed back into your context, you continue fixing
- Iteration cap (2) hit → remaining issues surfaced to user, turn ends
Override the loop for a turn with SKIP_CODEX_REVIEW=1 in the environment, or by user explicitly saying "ship it" / "skip review".
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

