When the codex-reviewer and ralph-reviewed Stop hooks invoke
`codex exec`, they pass `-o <outputFile>` so the verdict can be parsed
back from a known path, then append the user's `extra_args`. Two latent
bugs surfaced after the docs commit started promoting the shared
~/.claude/codex.json knobs to standalone users:
1. The previous filter dropped `-o` / `--output*` tokens individually
but not the value that followed a bare flag. With
extra_args: ["-o", "/tmp/other"], the filter left "/tmp/other" as a
stray positional that Codex treated as an extra prompt argument.
The new index-walk filter consumes both halves of paired flags
(-o, --output, --output-last-message) and drops the inline
--flag=value variants. Applied to both hooks.
2. ralph-reviewed honored `timeout_seconds` raw. A configured value at
or above the 1800s Stop hook timeout let Claude kill the hook
before it could parse Codex's output and surface a verdict. Now
clamped to [60, 1680] (matching the existing codex-reviewer
clamp), leaving a 120s buffer below the hook ceiling.
Bumps ralph-reviewed to 3.0.2 and codex-reviewer to 1.6.10 in
lockstep across each plugin.json and the root marketplace.json. The
ralph-reviewed troubleshooting README is updated to describe the new
clamp range rather than telling users to "increase to 1800".
Claude Code has internal protection on ~/.claude that blocks writes even
with explicit permissions and additionalDirectories configured. Moving
handoffs outside the protected zone eliminates approval prompts.
ralph-loop.md now builds rl from github.com/0xbigboss/rl via
bun build --compile if not already on PATH. Zero manual setup
needed — just run /ralph-reviewed:ralph-loop.
QA.md covers full e2e verification: rl init, agent work, rl done,
Codex review gate, feedback cycle, edge cases. qa.sh resets the test
repo and launches claude interactively with the QA prompt.
Ralph and Codex reviewer plugins defaulted to too few cycles,
causing loops to hit caps before completing complex tasks.
- ralph command: 15→30 max-iterations, 10→20 max-reviews
- ralph-loop plugin: 50→30 max-iterations (aligned with ralph command)
- codex-reviewer plugin: 10→20 max-cycles (command + hook fallback)
Remove Best Practices (duplicates ralphoff.md), Example Task Structure
(shows <promise> tags users don't write), and Review Gate section
(duplicates How It Works).
- Delete /tmp/codex-review-output-*.txt after reading (was leaking)
- Remove human-readable markdown body from serializeState (never read)
- Fix debug log path in ralph-loop.md to match actual location
(~/.claude/ralphs/{session_id}/debug.log, not /tmp/)
- Remove human-readable body from state file template (only YAML
frontmatter is read by the stop hook)
- Collapse 8-line Completion Promise Requirement + 19-line BLOCKED
Escape Condition into 2-line "Completion and Escape" section
- Keep all setup mechanics and confirmation output template intact
- Add codex.json symlink to install.sh for shared plugin config
- Update codex-handoff, codex-reviewer, ralph-reviewed hooks to use
centralized configuration instead of inline defaults
One-shot handoff gate that triggers Codex CLI on exit:
- Generates handoff context via /handoff skill
- Calls Codex to process handoff on session exit
- Feeds Codex output back to Claude as blocked feedback
- Session resumes with Codex context
Unlike codex-reviewer, this is a single-cycle gate (no review loops).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Claude Code now auto-loads hooks/hooks.json from plugin directories,
so explicit declaration causes duplicate loading. Also adds enabledPlugins
to settings template.
- ralph-reviewed: 1.8.7 → 1.8.8
- codex-reviewer: 1.6.8 → 1.6.9
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Claude Code auto-loads hooks/hooks.json by convention. Inline hooks
in plugin.json were not being loaded, causing Stop hooks to never
trigger.
- codex-reviewer: 1.6.5 → 1.6.6
- ralph-reviewed: 1.8.4 → 1.8.5
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When codex-reviewer has no active review gate, it was outputting
{"decision": "approve"} which could override other plugin hooks'
block decisions. Now it exits silently (no output) to let other
hooks like ralph-reviewed make the decision.
Also bumps versions: codex-reviewer to 1.6.5, ralph-reviewed to 1.8.4
Both codex-reviewer and ralph-reviewed plugins were missing the
"commands" field, preventing their slash commands from appearing
in the /plugin:command format.
The hooks configuration had an extra wrapper object causing Claude Code
to silently ignore the stop hook registration. This prevented the v1.8.0
hook from running entirely.
- Remove clipboard copy from handoff/ralphoff (hooks automate prompt passing)
- Add MANDATORY step markers with CRITICAL warnings for continuation
- Fix stop-hook to find state files in submodules by walking git hierarchy
- Check ACTIVE status when walking ancestors (inactive files don't mask parents)
- Update Step 0 to detect active gates in any ancestor repo
- Add head/grep to allowed-tools for verification commands
Fixes issue where Claude stops after first skill invocation in composite
commands like /ralph and /codex-reviewer:review.
Align all default values with the new 10-cycle default set in the
codex-reviewer command. Updates struct defaults, test assertions,
documentation examples, and fallback values.
getGitRoot() now walks up through submodule hierarchy using
git rev-parse --show-superproject-working-tree to find the true
root repo. Fixes issue where state files were not found when
Claude cd'd into a submodule.
- ralph-reviewed: v1.7.0 → v1.8.0
- codex-reviewer: v1.5.0 → v1.6.0
Add support for customizing max review cycles via command argument:
- `/codex-reviewer:review "focus" --max-cycles N`
- Defaults to 5 if not specified
- Matches ralph-loop argument style (description first, flags after)
Also fixes null task_description handling in stop-hook parser.
- Hook now reads from handoff_path at review time (latest content)
- Falls back to embedded task_description for backwards compatibility
- State file stores handoff path instead of full content
- Claude can update handoff between review cycles without touching state
- Added ALLOWED/FORBIDDEN sections clarifying what Claude can modify
Codex sometimes outputs partial responses like "Checked working directory"
instead of the required <review>APPROVE/REJECT</review> verdict tags.
Changes:
- Add CRITICAL output requirement section at top of prompt
- Include explicit anti-pattern warning for status messages
- Change shell commands from inline templates to instructions
- Add repeated reminder at end of prompt
- Update SKILL.md with new prompt structure and rationale
Bump version to v1.5.0.
When Codex approves, stop hooks now output a systemMessage that Claude
Code displays to the user. This provides visibility into what happened
(approval status, reviewer notes, iteration counts) instead of silent exit.
Changes:
- codex-reviewer: Show approval summary with review cycle and files
- ralph-reviewed: Show status for APPROVE, BLOCKED, max iterations,
and max review cycles scenarios
- Added JSDoc with reference to official hooks documentation
- Bumped plugin versions (codex-reviewer 1.4.0, ralph-reviewed 1.6.0)
- Add Step 0 guard in review.md to check for existing active gate
- If gate already active, tell Claude to just exit instead of recreating
- Update stop-hook feedback to explicitly warn against calling skill again
- Bump version to 1.3.0
Both codex-reviewer and ralph-reviewed now check for git repo before
calling Codex and provide actionable error messages instead of the
cryptic "Codex exited with status 1" from untrusted directory errors.
The review command now invokes /handoff before creating the state file,
giving Codex rich context about the work instead of a basic summary.
Changes:
- Restructure review.md into 3 steps: generate handoff, create state, exit
- Add YAML frontmatter with description and allowed-tools
- State file task_description now contains full handoff with XML sections:
<role>, <context>, <current_state>, <key_files>, <next_steps>
- Bump version to 1.2.0
Before: task_description was "Updated file X to do Y"
After: task_description includes reviewer framing, approach context,
what was done, key files with descriptions, verification steps
Display Codex review gate status in statusline alongside Ralph loop.
Changes:
- Add CodexReviewState struct to parse .claude/codex-review.local.md
- Display review cycle as 🔎 N/M (distinct from Ralph's 🔍)
- Move progressColor() to shared function for both Ralph and Codex
- Add 9 unit tests for CodexReviewState parsing and formatting
- Document state file locations and lookup commands in CLAUDE.md
- Fix codex-reviewer command to be explicit about git root path
Simplify configuration by having --max-reviews default to the
--max-iterations value when not explicitly specified, rather than
a hardcoded value of 5.
Enhance local marketplace manifest with complete plugin metadata:
- Add marketplace-level description in metadata section
- Include author name and email for each plugin
- Configure Stop hooks with command handlers and timeout settings
- Reorganize fields for consistent structure across plugins
Implement Codex-powered review gate plugin with fail-closed behavior:
- Stop hook with 1800s timeout to bypass Bash tool limits
- Strict gate: all errors block, requires explicit /cancel to escape
- Timeout clamping to [60s, 1680s] for safe hook execution
- State persistence before max-cycle check
- Execution error handling (spawn, signal, non-zero exit)
- Review history tracking with issue IDs across cycles
- Commands: review (start gate), cancel (escape gate)
Config stored at ~/.claude/codex/config.json separate from other tools.
Add built-in support for <promise>BLOCKED</promise> as a special
termination signal that exits the loop without triggering Codex review.
Use case: when Claude is genuinely blocked by external issues (missing
deps, pre-existing bugs, infra problems), it can cleanly exit without
wasting a review cycle on incomplete work.
- Add BLOCKED pattern detection in stop-hook.ts before completion check
- Add "Escape Condition: BLOCKED" section to ralph-loop.md
- Update README with BLOCKED documentation and feature comparison
- Bump version to v1.4.0
Allen