| name | monitor-pr |
| description | Watch an open pull request for new CI failures and review comments and drive it to a clean state. Uses the Monitor tool to stream PR status changes in real time so reactions are immediate instead of polled. Handles CodeRabbit nitpicks with judgment (do not blanket-skip) and treats "out of date" comments as still-relevant until proven otherwise. Replies to and resolves each thread as it's addressed. Triggers: "monitor the PR", "watch the PR for comments", "keep an eye on the PR", "address PR feedback as it lands", /monitor-pr.
|
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
gh api repos/<owner>/<repo>/pulls/<pr>/comments/<comment-databaseId>/replies \
-f body="Fixed."
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: ...:
TaskStop the monitor.- 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 — session-length, persistent: true, one stdout line =
one event, stop with TaskStop.
