Adopt main as the only mainline - #3
Conversation
Pre-existing uncommitted change dated 2026-07-28: a Codex call that dies mid-audit is not an approval; retry once, then stop and declare the plan UNREVIEWED out loud. Committed alone before the iteration changes so each lands separately. Verified: read the paragraph, matches the cross-review rule already recorded in global CLAUDE.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The audit loop ran up to 3 xhigh Codex rounds and only exited early on APPROVED, so a harmless WARNING verdict bought another 10-15 minute round. Measured 2026-08-02: three rounds, zero BLOCKED findings, ~45 minutes before any code. Now WARNING means incorporate the accepted findings and proceed with no further call; only BLOCKED (CRITICAL findings) triggers a re-audit, still capped at 3 iterations. The critical-evaluation and discussion-reply protocol is unchanged. Verified: read the revised Phase 2 end to end; verdict grammar matches codex-analyzer-role.md (VERDICT: APPROVED | WARNING | BLOCKED) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
claude-codex, execute-codex and both tdd variants re-reviewed on any non-APPROVED verdict, so a WARNING (HIGH-only) verdict bought another full xhigh Codex round. Session forensics showed a 6:1 blocked-to- approved ratio with most rounds churning on non-critical findings. Now: WARNING means fix the accepted HIGHs in one batch and proceed with no further call (the pre-push gate and CodeRabbit still review the final code); only BLOCKED/CRITICAL verdicts trigger a re-review; iteration caps are unchanged. Critical-evaluation and discussion-reply protocols untouched. Verified: grepped all four skills for stale 'without APPROVED' / 'WARNING -> re-review' phrasing, none remain Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The justification for skipping WARNING re-reviews cited a pre-push gate and CodeRabbit, which are operator-environment infrastructure this repo cannot assume; the justification now stands on its own (HIGHs are fixed and verified, only the paid re-verification round is skipped). WARNING paths now run post-fix verification (tests/lint, GREEN suite) and route MEDIUM/LOW handling instead of jumping straight to delivery. Route B HIGH-only branches name their path-specific fix mechanisms (subagents for the 3+ task path, codex-reply for the single-session path) so the no-Edit/Write rule cannot be violated. plan-codex WARNING description aligned to the analyzer-role grammar (at least one HIGH). Verified: grepped skills/ for 'pre-push gate and CodeRabbit', zero remain; re-read all four After-evaluation blocks for mechanism coverage Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…LOCKED-only re-review The commands/*.md compatibility entrypoints and both eval contracts still mandated re-review on WARNING and re-audit until APPROVED, so the policy shipped in the skills did not apply across all supported review loops and the repo's own evals would enforce the removed behavior. All entrypoints now match the skills: WARNING fixes accepted HIGHs, verifies, and proceeds with no further call; only BLOCKED iterates. BUGS.md drops the four HIGH findings fixed by this commit and the previous one; the two MEDIUMs stay queued. Verified: grep across commands/ and evals for 'without APPROVED' and WARNING-re-review phrasing returns only BLOCKED-scoped lines Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Review loops: re-review only on BLOCKED, single plan audit
Verified: read the BUGS.md diff, auto-routed findings only, no code touched Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The 3+ task re-review branches in commands/execute-codex.md and commands/tdd-execute-codex.md now trigger on CRITICAL only, matching the BLOCKED-only policy, and their iteration stops key on CRITICALs instead of approval. The obsolete until-APPROVED contract is removed from the plan-codex skill description, command description, eval expectation and all three README references. HIGH-only branches now carry MEDIUM/LOW findings forward the same way their approved branches do (delivery report for execute-codex, user prompt for the TDD variants). BUGS.md drops the fixed HIGH entries and duplicates; the blank-line LOW is fixed by the rewrite and its entry removed with it. Verified: grep across skills, commands and README for 'until approved' and CRITICAL/HIGH re-review phrasing returns only BLOCKED or CRITICAL scoped lines Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Skills backlog: all three queued HIGH findings fixed
📝 WalkthroughWalkthroughCodex workflows now distinguish ChangesCodex audit workflows
Estimated code review effort: 3 (Moderate) | ~20 minutes Sequence Diagram(s)sequenceDiagram
participant Workflow
participant Codex
participant Claude
participant Verification
Workflow->>Codex: submit plan, tests, or implementation for audit
Codex-->>Workflow: APPROVED, WARNING, or BLOCKED
Workflow->>Claude: fix accepted warning or critical/high findings
Claude->>Verification: run tests and lint
Verification-->>Workflow: verification result
Workflow->>Codex: re-review blocked or critical fixes
Codex-->>Workflow: updated verdict
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (3)
skills/plan-codex/evals/evals.json (1)
7-17: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd an evaluation for failed Codex audits.
The skill adds a mandatory retry and an
UNREVIEWEDstop result when the retry fails. These evaluations cover successful verdicts and availability, but not mid-call failure handling. Add a scenario that forces the first audit to fail, verifies exactly one retry with the audit prompt and instructions, and verifies that a second failure prevents Phase 3 delivery.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/plan-codex/evals/evals.json` around lines 7 - 17, Add a new evaluation scenario in the plan skill expectations that forces the initial Codex audit to fail, verifies exactly one retry using the same audit prompt and developer instructions, and expects an UNREVIEWED result when the retry also fails. Confirm the failed audit path stops before Phase 3 plan delivery and does not present the plan for execution.skills/plan-codex/SKILL.md (1)
63-66: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick winMake the WARNING no-call rule consistent across skills.
Both skills say that WARNING proceeds without another Codex call, but their critical-evaluation sections still permit
codex-replyfor questionable findings. Decide whether WARNING can invoke a discussion. If yes, call it an exception and say “no further re-audit.” If no, remove or limit that reply path.
skills/plan-codex/SKILL.md#L63-L66: clarify the WARNING wording.skills/plan-codex/SKILL.md#L85-L90: scope follow-up replies to the documented exception.skills/tdd-execute-codex/SKILL.md#L114-L115: align test-audit WARNING handling.skills/tdd-execute-codex/SKILL.md#L132-L134: align the BLOCKED-only re-call statement.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/plan-codex/SKILL.md` around lines 63 - 66, Make the VERDICT handling consistent by preserving WARNING as a reviewed result with no further Codex re-audit: update skills/plan-codex/SKILL.md lines 63-66 to state this explicitly, restrict follow-up codex-reply discussion in lines 85-90 to the documented BLOCKED exception, align WARNING handling in skills/tdd-execute-codex/SKILL.md lines 114-115, and make the re-call statement in lines 132-134 explicitly BLOCKED-only.skills/claude-codex/evals/evals.json (1)
28-28: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAssert the critical-evaluation step.
Line 28 checks HIGH fixes, verification, and no re-review. It does not check the required evaluation before accepting a finding. Add expectations for the R1.5 assessment and MEDIUM/LOW handling.
This requirement is defined in
skills/claude-codex/SKILL.mdLines 99-112.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/claude-codex/evals/evals.json` at line 28, Update the evaluation expectations in the relevant eval case to assert the required R1.5 assessment before accepting findings, including correct MEDIUM/LOW handling. Preserve the existing checks for HIGH fixes, verification, and skipping re-review, and align the assertions with the workflow defined by the R1.5 guidance in SKILL.md.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@commands/execute-codex.md`:
- Line 72: Update the review workflows to fail closed when CRITICAL findings
remain after the two-round cap: in commands/execute-codex.md at lines 72-72,
skills/execute-codex/SKILL.md at lines 87-87, and commands/tdd-execute-codex.md
at lines 147-147, explicitly stop before delivery and report the unresolved
CRITICAL findings.
- Line 72: Add the required critical-evaluation gate before each remediation
path, assessing correctness, context, and applicability before applying fixes or
counting review iterations. Update commands/execute-codex.md at lines 72 and
134-138, commands/tdd-claude-codex.md at lines 102-105 and 163-166, and
commands/tdd-execute-codex.md at lines 104-107, 147, and 233-237; preserve the
existing small-change, large-change, test-audit, implementation-review, Route A,
and Route B flows after the gate.
- Line 72: Preserve MEDIUM/LOW findings on both small-change paths by adding the
existing lower-severity reporting step before Phase 3 in
commands/execute-codex.md at lines 72-72 and skills/execute-codex/SKILL.md at
lines 87-87. Ensure Route A reports these findings for delivery or user choice
after HIGH fixes, matching the established handling in Route B and
skills/claude-codex/SKILL.md; both sites require the same direct change.
In `@commands/plan-codex.md`:
- Around line 52-53: The accepted-findings flow must apply one
critical-evaluation gate before proceeding. In commands/plan-codex.md lines
52-53, add the gate before folding WARNING findings or revising BLOCKED plans;
in commands/claude-codex.md lines 84-87, add the identical gate before fixing
accepted HIGH findings and skipping re-review. Require each accepted finding to
be validated for correctness, context, and applicability so valid HIGH or
CRITICAL findings cannot be dismissed.
- Line 2: Update the compatibility command described by the plan-codex workflow
to parse a structured VERDICT from the initial audit, retry parsing once on
failure, and stop with UNREVIEWED if parsing still fails. Permit codex-reply
only when the successful initial audit yields APPROVED, WARNING, or BLOCKED, and
restrict re-audits to the parser-level BLOCKED verdict rather than any response
containing the word BLOCKED.
In `@skills/plan-codex/SKILL.md`:
- Around line 49-52: Update the mandatory mid-call retry instructions in the
Codex availability audit to invoke the CLI with the plan path, audit prompt, and
contents of codex-analyzer-role.md as developer instructions, using the
installed codex exec syntax. Require the retry output to contain a valid
VERDICT; otherwise stop and report exactly that the Codex audit is incomplete
and the plan is UNREVIEWED, without proceeding to Phase 3 or implementation.
---
Nitpick comments:
In `@skills/claude-codex/evals/evals.json`:
- Line 28: Update the evaluation expectations in the relevant eval case to
assert the required R1.5 assessment before accepting findings, including correct
MEDIUM/LOW handling. Preserve the existing checks for HIGH fixes, verification,
and skipping re-review, and align the assertions with the workflow defined by
the R1.5 guidance in SKILL.md.
In `@skills/plan-codex/evals/evals.json`:
- Around line 7-17: Add a new evaluation scenario in the plan skill expectations
that forces the initial Codex audit to fail, verifies exactly one retry using
the same audit prompt and developer instructions, and expects an UNREVIEWED
result when the retry also fails. Confirm the failed audit path stops before
Phase 3 plan delivery and does not present the plan for execution.
In `@skills/plan-codex/SKILL.md`:
- Around line 63-66: Make the VERDICT handling consistent by preserving WARNING
as a reviewed result with no further Codex re-audit: update
skills/plan-codex/SKILL.md lines 63-66 to state this explicitly, restrict
follow-up codex-reply discussion in lines 85-90 to the documented BLOCKED
exception, align WARNING handling in skills/tdd-execute-codex/SKILL.md lines
114-115, and make the re-call statement in lines 132-134 explicitly
BLOCKED-only.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: a432a8d0-ceec-4314-9530-d2f8d3d2d47d
📒 Files selected for processing (14)
BUGS.mdREADME.mdcommands/claude-codex.mdcommands/execute-codex.mdcommands/plan-codex.mdcommands/tdd-claude-codex.mdcommands/tdd-execute-codex.mdskills/claude-codex/SKILL.mdskills/claude-codex/evals/evals.jsonskills/execute-codex/SKILL.mdskills/plan-codex/SKILL.mdskills/plan-codex/evals/evals.jsonskills/tdd-claude-codex/SKILL.mdskills/tdd-execute-codex/SKILL.md
| - `git diff HEAD` | ||
| - Original task requirements | ||
| 3. If reviewer finds CRITICAL/HIGH issues: fix directly with Edit/Write and re-review (max 2 rounds) | ||
| 3. CRITICAL issues → fix directly with Edit/Write and re-review (max 2 rounds). HIGH-only issues → fix with Edit/Write, re-run self-verification, proceed with no re-review call. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🔴 Critical | ⚡ Quick win
Fail closed when CRITICAL findings remain after the review cap.
Each route states a review limit but does not explicitly stop before delivery when CRITICAL findings remain.
commands/execute-codex.md#L72-L72: stop and report unresolved CRITICAL findings after two rounds.skills/execute-codex/SKILL.md#L87-L87: stop and report unresolved CRITICAL findings after two rounds.commands/tdd-execute-codex.md#L147-L147: stop and report unresolved CRITICAL findings after two rounds.
This matches the explicit blocked-stop behavior in the supplied skill and command workflows.
📍 Affects 3 files
commands/execute-codex.md#L72-L72(this comment)skills/execute-codex/SKILL.md#L87-L87commands/tdd-execute-codex.md#L147-L147
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@commands/execute-codex.md` at line 72, Update the review workflows to fail
closed when CRITICAL findings remain after the two-round cap: in
commands/execute-codex.md at lines 72-72, skills/execute-codex/SKILL.md at lines
87-87, and commands/tdd-execute-codex.md at lines 147-147, explicitly stop
before delivery and report the unresolved CRITICAL findings.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Apply the critical-evaluation gate in every command entrypoint.
The command files route CRITICAL/HIGH findings directly to remediation. Their corresponding skill policies require assessment of correctness, context, and applicability before fixing or counting an iteration.
commands/execute-codex.md#L72-L72: add the gate before small-change remediation.commands/execute-codex.md#L134-L138: add the gate before large-change remediation.commands/tdd-claude-codex.md#L102-L105: add the gate before test-audit fixes and re-audit.commands/tdd-claude-codex.md#L163-L166: add the gate before implementation-review fixes and re-review.commands/tdd-execute-codex.md#L104-L107: add the gate before test-audit fixes and re-audit.commands/tdd-execute-codex.md#L147-L147: add the gate before Route A remediation.commands/tdd-execute-codex.md#L233-L237: add the gate before Route B remediation.
This aligns the command entrypoints with the critical-evaluation rules in the supplied skill files.
📍 Affects 3 files
commands/execute-codex.md#L72-L72(this comment)commands/execute-codex.md#L134-L138commands/tdd-claude-codex.md#L102-L105commands/tdd-claude-codex.md#L163-L166commands/tdd-execute-codex.md#L104-L107commands/tdd-execute-codex.md#L147-L147commands/tdd-execute-codex.md#L233-L237
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@commands/execute-codex.md` at line 72, Add the required critical-evaluation
gate before each remediation path, assessing correctness, context, and
applicability before applying fixes or counting review iterations. Update
commands/execute-codex.md at lines 72 and 134-138, commands/tdd-claude-codex.md
at lines 102-105 and 163-166, and commands/tdd-execute-codex.md at lines
104-107, 147, and 233-237; preserve the existing small-change, large-change,
test-audit, implementation-review, Route A, and Route B flows after the gate.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Preserve MEDIUM/LOW findings on every small-change path.
Both paths fix HIGH findings and proceed without re-review, but they do not preserve remaining MEDIUM/LOW findings for delivery or user choice.
commands/execute-codex.md#L72-L72: add MEDIUM/LOW reporting before Phase 3.skills/execute-codex/SKILL.md#L87-L87: add the same reporting step before Phase 3.
This aligns Route A with the lower-severity handling already defined for Route B and skills/claude-codex/SKILL.md.
📍 Affects 2 files
commands/execute-codex.md#L72-L72(this comment)skills/execute-codex/SKILL.md#L87-L87
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@commands/execute-codex.md` at line 72, Preserve MEDIUM/LOW findings on both
small-change paths by adding the existing lower-severity reporting step before
Phase 3 in commands/execute-codex.md at lines 72-72 and
skills/execute-codex/SKILL.md at lines 87-87. Ensure Route A reports these
findings for delivery or user choice after HIGH fixes, matching the established
handling in Route B and skills/claude-codex/SKILL.md; both sites require the
same direct change.
| @@ -1,5 +1,5 @@ | |||
| --- | |||
| description: "Claude plans with Opus, Codex audits, loop until approved" | |||
| description: "Claude plans with Opus, Codex audits once, re-audit only on BLOCKED" | |||
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/bash
set -euo pipefail
echo "== files =="
git ls-files | rg '(^|/)(commands/plan-codex\.md|commands/claude-codex\.md|skills/plan-codex/SKILL\.md)$' || true
echo "== plan-codex outline/sections =="
if [ -f commands/plan-codex.md ]; then
wc -l commands/plan-codex.md
sed -n '1,140p' commands/plan-codex.md
fi
echo "== relevant search in file =="
rg -n "VERDICT|BLOCKED|WARNING|UNREVIEWED|retry|codex-reply|re-audit|rere-audit|evaluation|evaluate|failed" commands/plan-codex.md || true
echo "== skill counterpart sections if present =="
if [ -f skills/plan-codex/SKILL.md ]; then
wc -l skills/plan-codex/SKILL.md
sed -n '1,220p' skills/plan-codex/SKILL.md
fiRepository: hellosurbhi/claude-codex
Length of output: 10558
Enforce the audit state machine in the compatibility command.
commands/plan-codex.md allows re-audits from any response that contains BLOCKED, but the contract requires codex-reply only after a parser-level BLOCKED verdict. Add structured VERDICT: parsing, retry-once failure handling with an UNREVIEWED stop path, and only APPROVED/WARNING/BLOCKED from a successful initial audit before deciding whether to call codex-reply.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@commands/plan-codex.md` at line 2, Update the compatibility command described
by the plan-codex workflow to parse a structured VERDICT from the initial audit,
retry parsing once on failure, and stop with UNREVIEWED if parsing still fails.
Permit codex-reply only when the successful initial audit yields APPROVED,
WARNING, or BLOCKED, and restrict re-audits to the parser-level BLOCKED verdict
rather than any response containing the word BLOCKED.
| - WARNING (no CRITICAL) → fold the accepted findings into the plan, update `.claude/plan/<feature-name>.md`, go to Phase 3 with no further Codex call | ||
| - BLOCKED (CRITICAL findings) → address every CRITICAL, revise plan, update `.claude/plan/<feature-name>.md`, re-audit |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Define one critical-evaluation gate for accepted findings.
Both compatibility commands use “accepted” findings without defining the required correctness, context, and applicability checks. Without this gate, an agent can reject a valid HIGH or CRITICAL finding and continue without the promised review.
commands/plan-codex.md#L52-L53: add the evaluation before folding WARNING findings or revising BLOCKED plans.commands/claude-codex.md#L84-L87: add the same evaluation before fixing accepted HIGH findings and skipping re-review.
📍 Affects 2 files
commands/plan-codex.md#L52-L53(this comment)commands/claude-codex.md#L84-L87
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@commands/plan-codex.md` around lines 52 - 53, The accepted-findings flow must
apply one critical-evaluation gate before proceeding. In commands/plan-codex.md
lines 52-53, add the gate before folding WARNING findings or revising BLOCKED
plans; in commands/claude-codex.md lines 84-87, add the identical gate before
fixing accepted HIGH findings and skipping re-review. Require each accepted
finding to be validated for correctness, context, and applicability so valid
HIGH or CRITICAL findings cannot be dismissed.
| **MANDATORY Codex availability check**: `mcp__codex__codex` MUST be listed in the available tools (either in the tool list or in `<available-deferred-tools>`). Do NOT skip or bypass this phase. If the tool is genuinely absent from both locations, **stop and tell the user**: "Codex MCP is not available. This skill requires Codex for plan audit. Please add the Codex MCP server." Do not proceed without Codex — the audit loop is this skill's core value. | ||
|
|
||
| **MANDATORY mid-call failure handling**: a Codex call that errors, times out, or is aborted mid-audit (e.g. "sent no response or progress", MCP idle timeout, task failed) is NOT an approval and NOT a skippable step. Retry the call exactly once — via `codex exec --sandbox read-only` in Bash if the MCP transport is the thing failing (the per-session MCP connection does not pick up config changes until restart). If the retry also dies, **stop and tell the user**: "Codex audit incomplete — the review did not run. The plan is UNREVIEWED." Never proceed to Phase 3 or to implementation on a dead audit; an unreviewed plan must be labeled as such, out loud, every time. (Added 2026-07-28 after an xhigh audit was silently killed by a 1800s MCP idle timeout and work continued without it.) | ||
|
|
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== file location and line count =="
fd -a '^SKILL\.md$' . | sed 's#^\./##'
if [ -f skills/plan-codex/SKILL.md ]; then
wc -l skills/plan-codex/SKILL.md
echo "== relevant lines 1-120 =="
cat -n skills/plan-codex/SKILL.md | sed -n '1,120p'
fi
echo "== search for codex exec, analyzer, prompt, verdict =="
rg -n "codex exec|codex-analyzer-role|--sandbox read-only|MANDATORY mid-call|Codex audit|UNREVIEWED|VERDICT|codex-reply|available-deferred-tools|mcp__codex__codex" skills/plan-codex -S || trueRepository: hellosurbhi/claude-codex
Length of output: 11559
🌐 Web query:
claude code codex exec --sandbox read-only analyzer role developer instructions codex-analyzer-role.md
💡 Result:
The command claude code codex exec --sandbox read-only analyzer role developer instructions codex-analyzer-role.md is not a single standard command, but rather a combination of CLI tools, concepts, and file paths often used by developers to delegate tasks between Claude Code and the OpenAI Codex CLI [1][2][3]. Breakdown of the components: 1. claude code: Refers to the Claude Code CLI, an agentic tool for software development [4]. 2. codex exec: A command for the OpenAI Codex CLI that runs non-interactively [5][6]. It is typically used for scripting, CI/CD, or by another agent (like Claude Code) to perform an atomic, one-shot task [5][3][7]. 3. --sandbox read-only: A critical security flag that restricts the agent to reading files without allowing modification, creation, or deletion [8][9][2]. This is the industry-standard mode for automated code analysis [10][3]. 4. analyzer role: This refers to a specific "role" or persona defined for an agent [11][12]. In many Claude Code workflows (often found in .claude/agents/roles/ or .codex/skills/ directories), an analyzer role is designed to perform root cause analysis, evidence collection, and systemic investigation using an "evidence-first" approach [13][11][12]. 5. codex-analyzer-role.md: This is a configuration file (typically a Markdown file) that defines the instructions, behavioral constraints, and objectives for the agent acting in the analyzer role [13][12]. These files are used to enforce consistency and logic, such as ensuring the agent performs root cause analysis rather than implementation or avoiding low-confidence guesses [13][14]. In practice, a user or an automated script might be instructing Claude Code to use the codex exec tool to run an analysis task while forcing it to adhere to the behavioral rules defined in a file named codex-analyzer-role.md [1][13]. This pattern ensures that the AI's response is structured, evidence-based, and performed in a read-only environment [10][13][11].
Citations:
- 1: https://github.com/jleechanorg/claude-commands/blob/main/.claude/agents/codex-consultant.md
- 2: https://amanhimself.dev/blog/running-headless-codex-cli-inside-claude-code/
- 3: https://mcp.directory/blog/claude-codex-cli-skill-guide
- 4: https://code.claude.com/docs/en/overview
- 5: https://developers.openai.com/codex/noninteractive
- 6: https://developers.openai.com/codex/cli/reference.md
- 7: https://changyou.medium.com/two-ways-claude-code-calls-codex-one-shot-subprocess-vs-persistent-app-server-28f06dea98c4
- 8: https://developers.openai.com/codex/concepts/sandboxing
- 9: https://github.com/waroi/claude-multiagent-boiler-plate/blob/main/codex-integration-en.md
- 10: https://www.claudepluginhub.com/skills/robbyt-codex-plugins-codex/skills/codebase-analysis
- 11: https://github.com/wasabeef/claude-code-cookbook/blob/main/plugins/en/agents/roles/analyzer.md
- 12: https://github.com/wasabeef/claude-code-cookbook/blob/main/plugins/en/commands/role.md
- 13: https://github.com/catlog22/Claude-Code-Workflow/blob/07491b04ac30c9a2d887f443661288b1b7520832/.codex/skills/team-frontend-debug/roles/analyzer/role.md
- 14: https://github.com/catlog22/Claude-Code-Workflow/blob/e0b608b7f300f116234b02401ade1fa67095fdd7/.codex/skills/team-lifecycle-v4/roles/analyst/role.md
🌐 Web query:
CodeRabbit skills plan-codex SKILL.md codex exec --sandbox read-only
💡 Result:
In the context of CodeRabbit and AI agent integrations like Codex, a SKILL.md file is a standardized Markdown file that defines an AI agent skill according to the agent-skills specification [1]. These files act as portable, discoverable, and interoperable configurations that allow AI agents to understand and invoke external tools—such as the CodeRabbit CLI—without requiring manual setup [1][2]. The command codex exec --sandbox read-only (or similar variations involving skill execution) refers to the mechanism by which an AI agent like Codex executes these defined skills within a secure or restricted environment [3]. Key aspects of CodeRabbit SKILL.md and its integration include: 1. Standardization: Skills are packaged as SKILL.md files and stored in specific directories (e.g., /.codex/skills/ for Codex) [1][2]. The agent automatically detects these files to enable capabilities like code review or autofixing [1][2]. 2. Functionality: A SKILL.md file typically contains frontmatter defining the skill's name, description, and triggers (e.g., /.codex/skills/) [3][2].@coderabbit review), followed by instructions for the agent on how to execute the task [4][1][5]. For example, the code-review skill instructs the agent to run the CodeRabbit CLI (cr --agent) to perform analysis and present findings [4][1][6]. 3. Security and Execution: When a user triggers a skill, the agent (such as Codex) interprets the instructions within the SKILL.md file [1]. Using commands like exec with flags such as --sandbox or read-only is part of the agent's internal process for ensuring that tools run with appropriate permissions, isolating the execution to safe directories, or preventing unauthorized write operations to the system [3][7]. 4. Workflow: By using these skills, developers can trigger complex AI coding workflows—such as reviewing current changes or applying fixes—directly through natural language prompts within their IDE or CLI, without needing to manually context-switch or manage tool flags [3][1]. For Codex users, the recommended approach is to install the official CodeRabbit plugin via the marketplace, which manages these integrations, or to manually place the SKILL.md files into the agent's designated skills directory (
Citations:
- 1: https://docs.coderabbit.ai/cli/skills
- 2: https://github.com/coderabbitai/skills
- 3: https://docs.coderabbit.ai/cli/codex-integration
- 4: https://github.com/openai/plugins/blob/main/plugins/coderabbit/skills/coderabbit-review/SKILL.md
- 5: https://github.com/coderabbitai/skills/blob/main/skills/autofix/SKILL.md
- 6: https://docs.coderabbit.ai/cli
- 7: https://github.com/hatrd/cr-skill
🌐 Web query:
"codex exec" "--sandbox read-only" "codex-analyzer-role" "VERDICT"
💡 Result:
The command codex exec --sandbox read-only codex-analyzer-role VERDICT is not a standard built-in command for the OpenAI Codex CLI [1][2]. Instead, it is a specific invocation pattern often used in custom AI agent workflows and automation scripts (such as those found in GitHub repositories like Claude-Code-Workflow or similar agentic coding frameworks) [3][4][5]. Here is the breakdown of the components in that command: * codex exec: The core OpenAI Codex CLI command used for running non-interactive, headless tasks (such as CI/CD pipelines, automated analysis, or scripted reviews) [1][6][2]. * --sandbox read-only: A flag that restricts the environment, ensuring the Codex agent can only read files and answer questions without permission to modify the filesystem, run shell commands, or access the network [7][8][9]. * codex-analyzer-role: This is not a native Codex CLI flag. It typically refers to a configuration, prompt template, or "role" defined within a custom agent's skill library [3][10]. In these workflows, it instructs the agent to adopt a specific persona—such as a Senior Technical Analyst—to perform tasks like architecture evaluation, security auditing, or code quality analysis [10]. * VERDICT: This is a positional argument or instruction passed to the agent within the prompt, signaling that the agent should conclude its analysis by providing a structured decision, classification, or "verdict" (e.g., ACTIONABLE/NON_ACTIONABLE, PASS/FAIL, or APPROVE/REJECT) [3][4][5][11]. In practice, agents use this pattern to perform "blind" or independent verification of code, plans, or documentation [4][11]. By using --sandbox read-only, the workflow ensures the agent remains an objective observer rather than an active participant in modifying the codebase [7][11]. The "verdict" at the end forces the agent to commit to a binary or categorized outcome based on its analysis [4][11].
Citations:
- 1: https://developers.openai.com/codex/noninteractive
- 2: https://openai-codex.mintlify.app/cli/exec
- 3: https://github.com/catlog22/Claude-Code-Workflow/blob/e0b608b7f300f116234b02401ade1fa67095fdd7/.codex/skills/team-lifecycle-v4/roles/analyst/role.md
- 4: https://github.com/sd0xdev/sd0x-dev-flow/blob/main/skills/issue-analyze/SKILL.md
- 5: https://github.com/catlog22/Claude-Code-Workflow/blob/07491b04ac30c9a2d887f443661288b1b7520832/.codex/skills/team-perf-opt/roles/reviewer/role.md
- 6: https://github.com/baekenough/baekenough-skills/tree/main/codex-exec
- 7: https://github.com/openai/codex/blob/13c42a077c88a0d04ae7680a9891d2daf4558577/docs/sandbox.md
- 8: https://learn.chatgpt.com/docs/agent-approvals-security
- 9: https://github.com/openai/codex/blob/eaf81d3f/codex-rs/README.md
- 10: https://cdn.jsdelivr.net/npm/ccg-workflow@3.2.3/templates/prompts/codex/analyzer.md
- 11: https://github.com/leejuoh/claude-code-zero/blob/main/plugins/codex-advisor/skills/codex-verify/SKILL.md
🌐 Web query:
"codex exec" "developer-instructions" CODex CLI
💡 Result:
The codex exec command is the non-interactive mode for the Codex CLI, designed to allow you to run Codex as part of scripts, automated pipelines (CI/CD), or other command-line workflows without opening the interactive terminal UI (TUI) [1][2]. Key aspects of codex exec include: When to Use Use codex exec when you need to automate tasks, generate output that can be piped into other tools, or run Codex with pre-defined sandbox and permission settings in environments like CI/CD, pre-merge checks, or scheduled jobs [1][2]. Basic Usage You invoke it by passing a task prompt as an argument [2]. By default, it runs in a read-only sandbox [1]. Example: codex exec "Write a unit test for the file at src/main.py" Permissions and Sandbox You should configure the minimum permissions required for your automation [1][2]. Common flags include: - Read-only (default): Standard mode. - Allow edits: Use --sandbox workspace-write to allow file modifications [1]. - Broader access: Use --sandbox danger-full-access for advanced automation needs [1]. Piping and Stdin - If you want Codex to read its prompt from stdin, you can use codex exec - [1][2]. - Codex streams progress information to stderr while printing only the final output to stdout, making it suitable for command chaining [2]. Automation Best Practices - Authentication: While it reuses saved CLI credentials by default, it is standard practice in CI environments to provide credentials explicitly [1][2]. - Git Requirements: By default, Codex requires commands to run inside a Git repository to prevent accidental destructive changes. You can override this with the --skip-git-repo-check flag if necessary [1]. - Resuming: If you need to continue a previous non-interactive run, you can use the resume subcommand [1][2]. For a complete list of commands and flags, refer to the official Codex CLI reference documentation [3][4].
Citations:
- 1: https://developers.openai.com/codex/noninteractive
- 2: https://learn.chatgpt.com/docs/non-interactive-mode
- 3: https://developers.openai.com/codex/cli/reference
- 4: https://developers.openai.com/codex/cli/reference.md
🌐 Web query:
"Codex MCP" "mcp__codex__codex" "codex exec"
💡 Result:
In the context of the Model Context Protocol (MCP) and OpenAI's Codex CLI, the tools and commands you referenced represent two different ways of interacting with the Codex AI assistant, typically used when integrating Codex into other environments like Claude Code [1][2][3]. mcpcodexcodex This is an MCP tool used to initiate or interact with a persistent Codex conversation session [1][3]. It is designed to be called by an MCP-compliant host (such as Claude Code) to delegate tasks to Codex [1][4]. Because it supports session continuity, it allows the host to pass a prompt, receive a response along with a threadId, and then use a related tool (often called mcpcodexcodex-reply) to continue that specific conversation [1][5][6]. It is the preferred method for multi-turn interactions, as it maintains state and provides structured output [3][7][8]. codex exec This is a native command-line interface (CLI) operation [2][3]. When executed, it runs Codex as a one-shot, stateless process [2][3][7]. It is frequently used as a fallback mechanism when MCP tools are unavailable or for simple, non-interactive tasks where maintaining a conversation thread is unnecessary [3][7]. Unlike the MCP tool, codex exec does not natively support thread continuity; using it repeatedly for what should be a single conversation often results in mangled context or the loss of previous turns [3][7][8]. Summary of Differences Method | Transport | State | Best For --- | --- | --- | --- mcpcodexcodex | MCP Tool | Persistent (Threaded) | Complex, multi-turn, or collaborative tasks [1][7] codex exec | CLI Process | Stateless (One-shot) | Simple, independent, or single-call tasks [2][3][7] Authoritative community documentation and integration guides explicitly warn against using codex exec as a drop-in replacement for the MCP tool, noting that doing so can lead to stalls, truncated output, and the loss of session context [7][8].
Citations:
- 1: https://github.com/jackcongmac/claude-codex-bridge
- 2: https://github.com/xiaolai/codex-toolkit-for-claude/blob/main/GUIDE.md
- 3: https://github.com/mikeng-io/agent-skills/blob/master/skills/bridge-codex/SKILL.md
- 4: https://drewhyde.io/blog/codex-mcp-claude-code
- 5: https://github.com/lukeleekr/Symphony
- 6: https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep/blob/main/skills/auto-review-loop/SKILL.md
- 7: https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep/blob/main/skills/shared-references/reviewer-routing.md
- 8: /codex skill ignores Codex MCP, uses fragile
codex execpipe that stalls or truncates (~50% failure rate) garrytan/gstack#1036
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
import re
p = Path("skills/plan-codex/SKILL.md")
text = p.read_text()
# Extract retry block and main call block by headings/convention.
retry_re = re.search(
r"\*\*MANDATORY mid-call failure handling\*\*:.*?(?=\*\*Read `codex-analyzer-role\.md`)",
text,
re.S,
)
main_re = re.search(
r"\*\*Call `mcp__codex__codex` \(iteration 1\)\*:.*?(?=\*\*Parse the VERDICT line)",
text,
re.S,
)
print("retry_block:")
print(retry_re.group(0) if retry_re else "<missing>")
print("\ncomponents_present_in_retry:")
retry = retry_re.group(0) if retry_re else ""
for component in [
"codex exec",
"--sandbox read-only",
"plan file",
".claude/plan",
"codex-analyzer-role",
"developer-instructions",
"VERDICT",
]:
print(f"{component}: {bool(re.search(re.escape(component), retry, re.I))}")
print("\nmain_block:")
print(main_re.group(0) if main_re else "<missing>")
# Check whether code mentions parse/return unreviewed when CLI misses verdict.
print("\nmentions_unreviewed_in_recommended_docs:")
for line in text.splitlines():
if "UNREVIEWED" in line or "codex exec" in line or "VERDICT" in line:
print(line.strip())
PYRepository: hellosurbhi/claude-codex
Length of output: 1316
Make the CLI fallback run the same audit.
Line 51 sends codex exec --sandbox read-only without the plan path, audit prompt, or codex-analyzer-role.md as developer instructions. A no-input or unstructured Codex CLI call cannot produce the required VERDICT and cannot satisfy the retry requirement. Pass the same plan file, audit prompt, and analyzer instructions through the CLI interface; if the retry does not produce a valid VERDICT, treat it as an incomplete audit and report the plan as UNREVIEWED. Check the installed codex exec syntax for prompt/role input before relying on it here.
🧰 Tools
🪛 LanguageTool
[style] ~51-~51: Using a “neither–nor” construction here can make your writing sound more fluent.
Context: ...ess", MCP idle timeout, task failed) is NOT an approval and NOT a skippable step. Retry the call exactly once — via `cod...
(N_NOR)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/plan-codex/SKILL.md` around lines 49 - 52, Update the mandatory
mid-call retry instructions in the Codex availability audit to invoke the CLI
with the plan path, audit prompt, and contents of codex-analyzer-role.md as
developer instructions, using the installed codex exec syntax. Require the retry
output to contain a valid VERDICT; otherwise stop and report exactly that the
Codex audit is incomplete and the plan is UNREVIEWED, without proceeding to
Phase 3 or implementation.
1 participant
TL;DR (plain language)
Owner decision: every repo has exactly one long-lived branch, main. This repo's work has been living on local-customizations while main sat frozen at the upstream fork point. This PR fast-forwards main to everything (9 commits, zero conflicts: main is a clean ancestor). After merging, all future sessions branch off main, all PRs target main (already the repo default, so the auto-PR hook needs no special-casing), and local-customizations is retired as a mainline.
Merge this FIRST, then the README harvest PR (its diff collapses to README-only once this lands).
🤖 Generated with Claude Code
Summary by CodeRabbit