| name | handling-codex-reviews |
| description | Handles Codex GitHub PR review loops by waiting for reviews, fixing actionable feedback, resolving threads, and requiring Codex's main-thread thumbs-up. Use when Codex is a reviewer, a PR has `@codex review` activity, or Codex has added an `eyes` reaction to the PR description or latest review trigger. |
Handling Codex Reviews
Drive the Codex-specific review loop for a GitHub pull request.
Use this when
- A PR has
@codex review activity.
- Codex has added an
eyes reaction to the PR description or latest review trigger.
- Codex has left inline diff comments or top-level review feedback.
- Another skill, such as
babysitting-prs, detects Codex as a reviewer and needs the Codex loop completed.
Core workflow
- Resolve PR context (
owner/repo, PR number, branch).
- Run
scripts/codex_review_loop.sh state --pr <pr> --repo <owner/repo>.
- If
pending_review=true, run scripts/codex_review_loop.sh wait --pr <pr> --repo <owner/repo>. A clean Codex pass may complete as a 👍 reaction on the PR description or latest trigger instead of a review comment.
- Fix all actionable Codex feedback in one batch:
- inline diff comments from
actionable_diff_comments
- actionable top-level review bodies from
actionable_top_level_reviews
- Run relevant tests.
- Commit and push.
- Reply to each addressed inline diff comment with
Fixed in <sha>: <what changed>.
- For top-level review feedback, post a normal PR comment that includes the Codex review ID:
Fixed in <sha> for review <review-id>: <what changed>.
- Add 👍 reactions to addressed Codex comments.
- Resolve addressed review threads:
scripts/codex_review_loop.sh resolve --pr <pr> --repo <owner/repo> --comment-ids <id1,id2,...>.
- Check CI status:
scripts/codex_review_loop.sh checks --pr <pr> --repo <owner/repo>.
- If there is no review in progress and Codex has not approved the latest trigger for the current head, post exactly one fresh review trigger that includes the current head SHA:
@codex review
Head: <40-character-head-sha>
- Repeat until no pending review, no actionable Codex feedback, checks pass, the latest
@codex review trigger names the current head SHA, and Codex has approved with a 👍 reaction on the PR description or latest review trigger.
Important rules
- Never use
@codex in routine "fixed" replies.
- Only
@codex review should be used to request a new review pass.
- Do not consider Codex complete until
main_thread_approved=true.
- Use a bounded loop. Stop and ask for guidance if feedback is conflicting, unclear, or requires product judgement.
- Do not amend commits after posting
Fixed in <sha> replies.
- Always resolve conversations after addressing feedback and replying.
Commands
~/.config/agents/skills/handling-codex-reviews/scripts/codex_review_loop.sh state --pr 32 --repo owner/repo
~/.config/agents/skills/handling-codex-reviews/scripts/codex_review_loop.sh wait --pr 32 --repo owner/repo --timeout 900 --interval 20
~/.config/agents/skills/handling-codex-reviews/scripts/codex_review_loop.sh resolve --pr 32 --repo owner/repo --comment-ids 12345,67890
~/.config/agents/skills/handling-codex-reviews/scripts/codex_review_loop.sh checks --pr 32 --repo owner/repo
~/.config/agents/skills/handling-codex-reviews/scripts/codex_review_loop.sh state
State interpretation
pending_review=true: a recent @codex review trigger exists without newer Codex activity, or Codex has an eyes reaction on the PR description or latest review trigger with no newer Codex activity or thumbs-up reaction.codex_review_unavailable=true: Codex responded that the repo needs an environment before reviews can run. Do not wait for a thumbs-up or post another @codex review; report the setup blocker only if the user explicitly wants Codex review completed.actionable_diff_comments_count>0: unresolved Codex inline diff comments need fixes or explicit replies.actionable_top_level_reviews_count>0: actionable Codex top-level review feedback needs fixes or an explicit PR comment that references the review ID.main_thread_approved=false: Codex has participated, but the latest current-head @codex review trigger has not resulted in Codex's 👍 reaction on the PR description or review trigger.ready_for_codex=true: Codex has no pending review or actionable feedback and has approved the latest review trigger when required.
Reply templates
Fixed in <sha>: <concise summary of change>
Fixed in <sha> for review <review-id>: <concise summary of change>
@codex review
Head: <40-character-head-sha>
