monitor-pr

Drives a pull request to green by streaming its state through the Monitor tool and reacting the moment a check fails or a new review comment lands. Designed for CodeRabbit-reviewed PRs but works for human reviewers too.

Architecture: use the Monitor tool, not a sleep loop

This is load-bearing — do not substitute a Bash sleep loop. A loop in a single Bash call blocks the agent until it exits, so the agent can't react to events concurrently and misses interleaved work. Monitor streams each stdout line as a notification into the conversation, so the agent keeps full agency between events.

Start exactly one monitor at the top of the task with:

• persistent: true — PR reviews can take hours; don't let a timeout kill the watch mid-review.
• description — specific, e.g. "PR #493 state changes", because it appears in every notification.
• The polling script below as command.

Stop the monitor with TaskStop only when the exit condition is met or the user cancels.

The polling script

Resolve PR metadata first (once, before starting the monitor):

gh pr view --json number,url,headRepository,headRepositoryOwner,baseRepository

Then start the Monitor with this command (substitute PR, OWNER, REPO). It emits one line only when state changes — a quiet PR produces zero events, an eventful PR produces one event per transition.

PR=<number>; OWNER=<owner>; REPO=<repo>
last=""
while true; do
  checks=$(gh pr checks "$PR" --json bucket 2>/dev/null || echo '[]')
  failing=$(jq '[.[] | select(.bucket=="fail" or .bucket=="cancel")] | length' <<<"$checks")
  pending=$(jq '[.[] | select(.bucket=="pending")] | length' <<<"$checks")
  unresolved=$(gh api graphql --paginate -f query='
    query($o:String!,$r:String!,$n:Int!,$endCursor:String){
      repository(owner:$o,name:$r){
        pullRequest(number:$n){
          reviewThreads(first:100, after:$endCursor){
            nodes{ isResolved }
            pageInfo{ hasNextPage endCursor }
          }
        }
      }
    }' -f o="$OWNER" -f r="$REPO" -F n="$PR" 2>/dev/null \
    | jq -s '[.[].data.repository.pullRequest.reviewThreads.nodes[]
             | select(.isResolved==false)] | length')
  state="fail=${failing:-?} pending=${pending:-?} unresolved=${unresolved:-?}"
  if [ "$state" != "$last" ]; then
    if [ "$failing" = "0" ] && [ "$pending" = "0" ] && [ "$unresolved" = "0" ]; then
      echo "clean: all checks pass, none pending, zero unresolved threads"
    else
      echo "change: $state — triage needed"
    fi
    last="$state"
  fi
  sleep 60 || exit 0
done

Monitor discipline:

• 60s poll floor. Don't drop below; you'll rate-limit yourself against the GitHub API and waste tokens on noise.
• Only state transitions emit. Stable state is silent.
• Transient failures are tolerated (2>/dev/null on both gh calls, || echo '[]' on gh pr checks) so a single API blip yields a degraded poll instead of killing the watch. The ${var:-?} fallbacks in the state string ensure partial results still produce an event rather than a blank state.
• One line per event keeps notifications terse — Monitor turns every stdout line into a chat notification.

Reacting to a change: event

When the monitor emits change: fail=N pending=P unresolved=M, do the following. Keep the monitor running the whole time.

1. Failing checks

gh pr checks <pr>
gh run view --log-failed <run-id>

Fix the root cause in code. Never bypass with --no-verify, flaky-retry loops, or skip directives.

2. Fetch every review thread with resolution + outdated state

REST doesn't expose isResolved/isOutdated. Use GraphQL, and paginate via --paginate + an $endCursor variable so PRs with >100 threads don't silently truncate:

gh api graphql --paginate -f query='
query($owner:String!, $repo:String!, $number:Int!, $endCursor:String) {
  repository(owner:$owner, name:$repo) {
    pullRequest(number:$number) {
      reviewThreads(first:100, after:$endCursor) {
        nodes {
          id
          isResolved
          isOutdated
          path
          line
          originalLine
          comments(first:50) {
            nodes { databaseId author { login } body createdAt }
          }
        }
        pageInfo { hasNextPage endCursor }
      }
    }
  }
}' -f owner=<owner> -f repo=<repo> -F number=<pr>

gh --paginate walks pageInfo.endCursor until hasNextPage: false and emits one JSON document per page to stdout. When consuming, slurp with jq -s and iterate across pages (e.g. jq -s '[.[].data.repository.pullRequest.reviewThreads.nodes[]] | ...').

3. Triage each unresolved thread

Judge each one individually. Do not blanket-skip any category.

• Human comment — address it.
• CodeRabbit actionable — address it.
• CodeRabbit nitpick — DO NOT auto-dismiss. CodeRabbit is often overly polite and hides real issues under "nitpick". Read each one and decide: is this a legit correctness/clarity/safety concern, or purely stylistic noise that conflicts with repo conventions? Only skip if the suggestion is actively wrong, contradicts CLAUDE.md, or is irrelevant to the change's intent. When in doubt, apply the fix.
• Thread marked isOutdated: true — DO NOT skip. "Outdated" means the line numbers moved since the comment was written, not that the feedback is obsolete. Re-read the comment against the current code at that region and decide whether the concern still applies. Usually it does.

4. Fix in code

Actually edit source. Never reply-without-fix. If a comment implies a design decision the user should own, stop your own work and ask — but leave the monitor running. It's silent while state is stable, costs nothing, and will resume emitting as soon as the discussion ends in a push or a resolve.

5. Reply + resolve each addressed thread

# Reply (the in_reply_to form of the review comments API)
gh api repos/<owner>/<repo>/pulls/<pr>/comments/<comment-databaseId>/replies \
  -f body="Fixed."

# Resolve
gh api graphql -f query='
mutation($threadId:ID!) {
  resolveReviewThread(input:{threadId:$threadId}) {
    thread { isResolved }
  }
}' -f threadId=<thread-node-id>

For threads you intentionally skipped (e.g., a nitpick that's wrong), reply with one sentence explaining why, then still resolve the thread.

6. Commit + push

Bundle the round into one commit following repo style (CLAUDE.md: one-line type(scope): summary, ≤72 chars).

This repo's CLAUDE.md says: "Always confirm with human before doing a git commit or a git push." Honor that unless the user has explicitly told you to run autonomously.

Do not stop the monitor after pushing. A new push triggers new CI runs and may draw new CodeRabbit follow-ups; the monitor will fire again when they land, and the loop continues naturally.

Exit

When the monitor emits clean: ...:

1. TaskStop the monitor.
2. Report a summary: what was fixed, what was intentionally skipped and why (one bullet per skipped thread), final check + thread counts.

Guardrails

• Always use Monitor. Not sleep in a Bash call, not manual repeated polling. Monitor streams events so the agent reacts immediately and runs concurrently with other work.
• Never skip outdated comments blindly. isOutdated = line moved.
• Never blanket-dismiss CodeRabbit nitpicks. Judge each on merit.
• Never bypass failing checks with --no-verify or similar.
• Confirm before git push unless running autonomously.
• Pause and ask if a comment implies a design decision the user should own, rather than guessing — but keep the monitor running during the discussion. It's silent while state is stable.
• One-line commit messages, detail in the PR body.

Related

• CLAUDE.md — repo commit/PR conventions, CodeRabbit reply protocol.
• Monitor tool — sessi