Watch CI

Monitor GitHub PR CI checks, notify on completion via macOS system notification, and investigate failures.

Scripts

• Notification: ~/.claude/skills/watch-ci/scripts/notify.sh
• CI Checker: ~/.claude/skills/watch-ci/scripts/check-ci.sh

Workflow

Step 1: Identify the PR

Determine which PR to watch:

# If user provides a PR number or URL, use it directly
# Otherwise, detect from current branch
gh pr view --json number,title,url,headRefName --jq '{number,title,url,headRefName}'

If no PR is found for the current branch, inform the user and stop.

Step 2: Show Initial Status

Before starting the watch loop, show the current state:

gh pr checks --json name,state,bucket,workflow

Report to the user:

• PR number and title
• Total number of checks
• Current status breakdown (passed/pending/failed)

Step 3: Poll Loop

IMPORTANT: You must poll every 20 seconds until all checks reach a terminal state (pass or fail).

Use this polling approach:

# Run check and capture result
RESULT=$(bash ~/.claude/skills/watch-ci/scripts/check-ci.sh [PR_NUMBER])
echo "$RESULT"

Parse the JSON result. Based on status:

• pending: Wait 20 seconds, then check again

  sleep 20
  

  Print a brief progress update each cycle (e.g., "Checking... 5/8 passed, 3 pending")

• pass: All checks green - proceed to Step 4 (Success)

• fail: One or more checks failed - proceed to Step 5 (Failure)

• error or no_checks: Report the issue and stop

Keep the loop going until a terminal state is reached. Do NOT give up or ask the user to check manually.

Step 4: All Checks Passed

When all CI checks pass:

1. Send system notification:

   bash ~/.claude/skills/watch-ci/scripts/notify.sh success "All CI checks passed! PR #<number>"
   

2. Report the final status to the user with a summary of all checks.

3. Done! The CI is green.

Step 5: CI Check Failed

When one or more CI checks fail:

1. Send system notification:

   bash ~/.claude/skills/watch-ci/scripts/notify.sh error "CI check failed: <check-name>. PR #<number>"
   

2. Identify which checks failed:

   gh pr checks [PR_NUMBER] --json name,state,bucket,link --jq '[.[] | select(.bucket == "fail" or .bucket == "cancel")]'
   

3. Investigate the failure - fetch the failed run logs:

   # List failed runs for this PR's branch
   gh run list --branch <branch> --status failure --limit 5 --json databaseId,name,conclusion
   
   # Get logs for the failed run
   gh run view <run-id> --log-failed
   

4. Analyze the logs and determine the root cause:

   • Build errors: check compiler/transpiler output
   • Test failures: identify which tests failed and why
   • Lint errors: identify which files/rules are violated
   • Timeout: check if tests are hanging

5. Fix the problem:

   • Make the necessary code changes to fix the failure
   • Commit the fix
   • Push to the PR branch
   • Return to Step 3 to watch the new CI run

6. If the fix requires user input or the failure is unclear, explain the issue and ask the user for guidance before proceeding.

Notes

• The polling interval is 20 seconds to balance responsiveness with API rate limits
• System notifications use macOS osascript (works on macOS only, degrades gracefully elsewhere)
• The gh CLI must be authenticated and have access to the repository
• If the PR has no checks configured, report this and stop
• Maximum reasonable watch time: if CI has been running for over 60 minutes with no progress, warn the user