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
OutlineDriven