codex-reflector

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

Claude Code 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)
• Python 3.8+ (stdlib only, no pip dependencies)

Install

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

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	Blocks if unresolved FAIL reviews exist
PreCompact	Context compaction	sync	Summarizes critical session context

Environment Variables

Variable	Default	Description
CODEX_REFLECTOR_ENABLED	1	Set to 0 to disable all hooks
CODEX_REFLECTOR_MODEL	(codex default)	Override model for codex exec
CODEX_REFLECTOR_DEBUG	0	Set to 1 for stderr diagnostics

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

How It Works

Code Reviews (async)

After Write/Edit tool calls, Codex reviews the change in a read-only sandbox. The verdict (PASS/FAIL/UNCERTAIN) and full opinion are delivered as a systemMessage on the next conversation turn. Codex's opinions are always returned regardless of verdict.

FAIL verdicts are tracked in a state file. The Stop hook prevents Claude from finishing until all FAILs are resolved.

Thinking Reflection (sync)

After each thinking MCP tool step (sequential-thinking, actor-critic, shannon), Codex provides immediate metacognitive observations: coherence checks, blind spots, overlooked alternatives, logical gaps. Advisory only — no PASS/FAIL blocking.

Bash Failure Diagnostics (async)

When Bash commands fail, Codex diagnoses root cause and suggests remediation steps.

PreCompact Summary (sync)

Before context compaction, Codex reads the session transcript tail and produces a summary of key decisions, unresolved issues, current task state, and important file paths.

Verdict Parser

The parser extracts PASS/FAIL from Codex's output:

• Strips markdown noise (**, backticks, emoji)
• Checks first 5 non-empty lines for verdict words
• Supports keyed formats (Verdict: PASS, result=FAIL)
• Contradictory signals (both PASS and FAIL) resolve to UNCERTAIN
• Fail-open: UNCERTAIN never blocks

Self-test: python3 scripts/codex-reflector.py --test-parse

Safety

• Fail-open: All errors result in exit 0 (approve). The plugin never blocks Claude due to its own failures.
• Read-only sandbox: Codex runs with --sandbox read-only — it cannot modify files.
• Infinite loop prevention: Stop hook checks stop_hook_active flag.
• Concurrent access: State file uses fcntl.flock for safe concurrent writes.

License

Apache-2.0