codex-reflector

Outline-Driven Development — Reflector

Codex CLI meta-reflection layer for Outline-Driven Development. Add-on for the Claude Code plugin, with a native oh-my-pi port.

Methodology: outline-driven-development  ·  Claude Code plugin: odin-claude-plugin  ·  Site: outlinedriven.github.io

---

Independent critic, oracle, and metacognition layer using OpenAI Codex CLI.

The agent acts. Codex reviews. Every code change gets a second opinion. Every thinking step gets metacognitive reflection from a different model family.

Requirements

• Codex CLI on PATH (codex exec must work) — required by both surfaces.

The reflector ships in two surfaces; install whichever matches your agent:

• Claude Code plugin — the original single-file Python hook. Needs Python 3.8+ (stdlib only, no pip dependencies).
• oh-my-pi (omp) — a native TypeScript port, no Python runtime. Needs the omp CLI.

---

Claude Code plugin

A single-file Python hook (scripts/codex-reflector.py, stdlib only) wired through hooks/hooks.json. Requires Python 3.8+.

Install

claude plugin marketplace add OutlineDriven/odin-reflector; claude plugin install codex-reflector@odin-reflector

Activation

Place this plugin at ~/.claude/codex-reflector/ and restart Claude Code.

~/.claude/codex-reflector/
├── .claude-plugin/plugin.json
├── hooks/hooks.json
├── scripts/codex-reflector.py
├── LICENSE
├── README.md
└── .gitignore

Hook events

Event	Trigger	Mode	Purpose
PostToolUse	Write, Edit, morph-edit	async	Code review with PASS/FAIL/UNCERTAIN verdict
PostToolUse	sequential-thinking, actor-critic, shannon	sync	Metacognitive reflection (advisory, no verdict)
PostToolUseFailure	Bash	async	Root cause diagnosis for failed commands
Stop	Agent finishing	sync	Fresh holistic review; blocks on FAIL only (PASS/UNCERTAIN settle)
PreCompact	Context compaction	sync	Summarizes critical session context

Use with Cursor

Cursor can run this plugin through its Claude Code third-party hooks compatibility layer.

Install as a Cursor plugin

This repository includes native Cursor plugin metadata at .cursor-plugin/plugin.json.

To install it as a local Cursor plugin, copy or symlink this repository into:

~/.cursor/plugins/local/codex-reflector

Then reload Cursor. The plugin components are auto-discovered from this repository:

• hooks/hooks.json
• rules/codex-reflector-usage.mdc
• skills/codex-reflector/SKILL.md
• agents/codex-reflector-reviewer.md
• commands/install-cursor-plugin.md

Direct-export hooks

1. Enable Third-party skills in Cursor Settings.
2. Install the direct-export Claude settings:

scripts/install-cursor.sh

That writes ~/.claude/settings.json with absolute paths to this checkout. To install into a specific project instead, pass the project path:

scripts/install-cursor.sh /path/to/project

When this repository itself is opened in Cursor, the checked-in .claude/settings.json also works directly because Cursor provides CLAUDE_PROJECT_DIR.

Cursor compatibility notes:

• PostToolUse, Stop, and PreCompact run through Cursor's Claude hook compatibility.
• PostToolUseFailure is included in the export for Claude parity, but Cursor does not currently list it in its Claude hook mapping table.
• Cursor treats Claude Stop blocks as follow-up messages, so a FAIL Stop review causes the agent to continue with Codex feedback instead of hard-stopping the UI.
• The direct export mirrors the Claude plugin matcher. Cursor only fires the parts whose tool names are exposed through its Claude hook compatibility layer.

---

oh-my-pi (omp)

A native TypeScript port of this reflector ships at omp/codex-reflector.ts — no Python runtime; it calls codex exec directly. It registers oh-my-pi hooks that mirror the Claude plugin: code review on write/edit/ast_edit and Fast-Apply MCP edits, root-cause diagnostics on failed bash and Fast-Apply calls, metacognitive reflection on thinking-MCP steps (sequential, shannon), and a pre-compaction session summary.

Install the omp CLI

Skip if you already have it (more options):

curl -fsSL https://omp.sh/install | sh       # macOS / Linux
bun install -g @oh-my-pi/pi-coding-agent      # any platform, bun >= 1.3.14

The module is an oh-my-pi extension — a default-export factory that registers handlers via pi.on. Its Stop gate uses the session_stop event, which the extension surface guarantees, so installing it as an extension is the canonical path.

Install as a hook