ao review-check

Check PRs for review comments and trigger agents to address them

The ao review-check command scans open pull requests for pending review comments and automatically sends agents messages to address them. This is useful for proactively handling review feedback without manual intervention.

Syntax

ao review-check [project] [options]

Arguments

project · string

Project ID to check. If omitted, checks all projects.

Options

--dry-run · flag

Show what would be done without actually sending messages to agents

How It Works

The command performs these steps:

1. Fetch sessions - Lists all sessions for the specified project (or all projects)
2. Filter PRs - Identifies sessions with open pull requests
3. Check reviews - Queries GitHub GraphQL API for each PR to check:
   • Review decision (APPROVED, CHANGES_REQUESTED, etc.)
   • Unresolved review threads
4. Notify agents - Sends a message to each agent with pending reviews

Review Detection

A session is considered to have pending reviews if either:

• The PR has a CHANGES_REQUESTED review decision
• The PR has one or more unresolved review threads

Message Format

When reviews are detected, the command sends this message to the agent:

There are review comments on your PR. Check with `gh pr view --comments` 
and `gh api` for inline comments. Address each one, push fixes, and reply.

The agent can then use GitHub CLI commands to fetch and address the comments.

Examples

Check all projects

ao review-check

Scans all sessions across all projects for pending reviews.

Check a specific project

ao review-check frontend

Checks only sessions belonging to the frontend project.

Dry run to preview actions

ao review-check --dry-run

Shows which sessions have pending reviews without sending messages:

Found 2 sessions with pending reviews:

  frontend-1  PR #123
    Decision: CHANGES_REQUESTED
    Comments: 3
    (dry run — would send fix prompt)

  frontend-2  PR #124
    Comments: 1
    (dry run — would send fix prompt)

Output

Sessions with pending reviews

Found 2 sessions with pending reviews:

  frontend-1  PR #123
    Decision: CHANGES_REQUESTED
    Comments: 3
    -> Fix prompt sent

  backend-1  PR #456
    Comments: 1
    -> Fix prompt sent

No pending reviews

No pending review comments found.

Implementation Details

GraphQL Query

The command uses GitHub’s GraphQL API to efficiently fetch review data:

query($owner:String!, $name:String!, $pr:Int!) {
  repository(owner:$owner, name:$name) {
    pullRequest(number:$pr) {
      reviewDecision
      reviewThreads(first:100) {
        nodes {
          isResolved
        }
      }
    }
  }
}

This avoids REST API pagination and fetches all necessary data in one request.

Agent Interruption

Before sending the message, the command:

1. Sends Ctrl-C to interrupt any running command
2. Waits 500ms for the interruption to take effect
3. Sends Ctrl-U to clear any partial input
4. Waits 200ms
5. Sends the review message
6. Presses Enter to submit

This ensures the agent receives the message even if it’s currently busy.

Error Handling

Unknown project

Error: Unknown project: xyz

Cause: The specified project ID does not exist in agent-orchestrator.yaml.

Solution: Check your configuration file and use a valid project ID from ao status.

PR access denied

If a PR cannot be accessed (private repo, insufficient permissions), it is silently skipped. No error is displayed.

Solution: Ensure the gh CLI is authenticated with appropriate permissions:

gh auth status
gh auth login

Failed to send message

Error: Failed to send: ...

Cause: Tmux session is not running or target is invalid.

Solution: Verify the session exists with ao status and is in a running state.

Use Cases

Automated review response workflow

Set up a cron job to periodically check for reviews:

# Check every 30 minutes during work hours
*/30 9-17 * * 1-5 cd /path/to/project && ao review-check

CI/CD integration

Trigger review checks after a PR review event:

# .github/workflows/review-trigger.yml
on:
  pull_request_review:
    types: [submitted]

jobs:
  notify-agent:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger review check
        run: |
          ssh orchestrator-host "cd /path/to/agent-orchestrator && ao review-check"

Manual review triage

Before end of day, check all pending reviews:

ao review-check --dry-run

Review the output, then run without --dry-run to send messages.

Prerequisites

• gh CLI - Must be authenticated with the repository
• GraphQL API access - Repository must be accessible via GitHub GraphQL API
• tmux - Sessions must be running in tmux for message delivery

Related Commands

• ao send - Manually send messages to sessions
• ao status - View PR status for all sessions
• Auto-reactions guide - Configure automatic review handling