gh-pr-review

gh-pr-review is a GitHub CLI extension that finally brings inline PR review comments to the terminal.
GitHub’s built-in gh tool does not show inline comments or review threads — but this extension does.

With gh-pr-review, you can:

View complete inline review threads with file and line context
See unresolved comments during code review
Reply to inline comments directly from the terminal
Resolve review threads programmatically
Export structured output ideal for LLMs and automated PR review agents

Designed for developers, DevOps teams, and AI systems that need full pull request review context, not just top-level comments.

Blog post: gh-pr-review: LLM-friendly PR review workflows in your CLI — explains the motivation, design principles, and CLI + JSON output examples.

Quickstart
Review view
Backend policy
Additional docs
Design for LLMs & Automated Agents
Using as a Skill

Quickstart

The quickest path from opening a pending review to resolving threads:

Install or upgrade the extension.

gh extension install agynio/gh-pr-review
# Update an existing installation
gh extension upgrade agynio/gh-pr-review

Start a pending review (GraphQL). Capture the returned id (GraphQL node).
```
gh pr-review review --start -R owner/repo 42
{
"id": "PRR_kwDOAAABbcdEFG12",
"state": "PENDING"
}
```
Pending reviews omit submitted_at; the field appears after submission.

Add inline comments with the pending review ID (GraphQL). The review --add-comment command fails fast if you supply a numeric ID instead of the required PRR_… GraphQL identifier.

gh pr-review review --add-comment \ --review-id PRR_kwDOAAABbcdEFG12 \ --path internal/service.go \ --line 42 \ --body "nit: use helper" \ -R owner/repo 42

{ "id": "PRRT_kwDOAAABbcdEFG12", "path": "internal/service.go", "is_outdated": false, "line": 42 }

Inspect review threads (GraphQL). review view surfaces pending review summaries, thread state, and inline comment metadata. Thread IDs are always included; enable --include-comment-node-id when you also need the individual comment node identifiers.

gh pr-review review view --reviewer octocat -R owner/repo 42
{
"reviews": [
{
"id": "PRR_kwDOAAABbcdEFG12",
"state": "COMMENTED",
"author_login": "octocat",
"comments": [
{
"thread_id": "PRRT_kwDOAAABbcdEFG12",
"path": "internal/service.go",
"author_login": "octocat",
"body": "nit: prefer helper",
"created_at": "2024-05-25T18:21:37Z",
"is_resolved": false,
"is_outdated": false,
"thread_comments": []
}
]
}
]
}

Use the thread_id values with comments reply to continue discussions. If you are replying inside your own pending review, pass the associated PRR_… identifier with --review-id.

gh pr-review comments reply \
  --thread-id PRRT_kwDOAAABbcdEFG12 \
  --body "Follow-up addressed in commit abc123" \
  -R owner/repo 42

Submit the review (GraphQL). Reuse the pending review PRR_… identifier when finalizing. Successful submissions emit a status-only payload. GraphQL-level errors are returned as structured JSON for troubleshooting.

gh pr-review review --submit \ --review-id PRR_kwDOAAABbcdEFG12 \ --event REQUEST_CHANGES \ --body "Please add tests" \ -R owner/repo 42

{ "status": "Review submitted successfully" }

On GraphQL errors, the command exits non-zero after emitting:

{
  "status": "Review submission failed",
  "errors": [
    { "message": "mutation failed", "path": ["mutation", "submitPullRequestReview"] }
  ]
}

Inspect and resolve threads (GraphQL). Array responses are always [] when no threads match.

gh pr-review threads list --unresolved --mine -R owner/repo 42

[ { "threadId": "R_ywDoABC123", "isResolved": false, "path": "internal/service.go", "line": 42, "isOutdated": false } ]

gh pr-review threads resolve --thread-id R_ywDoABC123 -R owner/repo 42

{
  "thread_node_id": "R_ywDoABC123",
  "is_resolved": true
}

Review view

gh pr-review review view emits a GraphQL-only snapshot of pull request discussion. The response groups reviews → parent inline comments → thread replies, omitting optional fields entirely instead of returning null.

Run it with either a combined selector or explicit flags:

gh pr-review review view -R owner/repo --pr 3

Install or upgrade to v1.6.0 or newer (GraphQL-only thread resolution and minimal comment replies):

gh extension install agynio/gh-pr-review
# Update an existing installation
gh extension upgrade agynio/gh-pr-review

Command behavior

Single GraphQL operation per invocation (no REST mixing).
Includes all reviewers, review states, and threads by default.
Replies are sorted by created_at ascending.
Output exposes author_login only—no user objects or html_url fields.
Optional fields (body, submitted_at, line) are omitted when empty.
comments is omitted entirely when a review has no inline comments.
thread_comments is required for every inline comment and always present (empty arrays indicate no replies).

For the full canonical response structure, see docs/SCHEMAS.md.

Filters

Flag	Purpose
`--reviewer <login>`	Only include reviews authored by `<login>` (case-insensitive).
`--states <list>`	Comma-separated review states (`APPROVED`, `CHANGES_REQUESTED`, `COMMENTED`, `DISMISSED`).
`--unresolved`	Keep only unresolved threads.
`--not_outdated`	Exclude threads marked as outdated.
`--tail <n>`	Retain only the last `n` replies per thread (0 = all). The parent inline comment is always kept; only replies are trimmed.
`--include-comment-node-id`	Add GraphQL comment node identifiers to parent comments and replies.

Examples

# Default: return all reviews, states, threads
gh pr-review review view -R owner/repo --pr 3
Unresolved threads only
gh pr-review review view -R owner/repo --pr 3 --unresolved
Focus changes requested from a single reviewer; keep only latest reply per thread
gh pr-review review view -R owner/repo --pr 3 --reviewer alice --states CHANGES_REQUESTED --tail 1
Drop outdated threads and include comment node IDs
gh pr-review review view -R owner/repo --pr 3 --not_outdated --include-comment-node-id

Replying to threads

Use the thread_id values surfaced in the report when replying.

gh pr-review comments reply 3 -R owner/repo \
  --thread-id PRRT_kwDOAAABbcdEFG12 \
  --body "Follow-up addressed in commit abc123"

Backend policy

Each command binds to a single GitHub backend—there are no runtime fallbacks.

Command	Backend	Notes
`review --start`	GraphQL	Opens a pending review via `addPullRequestReview`.
`review --add-comment`	GraphQL	Requires a `PRR_…` review node ID.
`review view`	GraphQL	Aggregates reviews, inline comments, and replies (used for thread IDs).
`review --submit`	GraphQL	Finalizes a pending review via `submitPullRequestReview` using the `PRR_…` review node ID (executed through the internal `gh api graphql` wrapper).
`comments reply`	GraphQL	Replies via `addPullRequestReviewThreadReply`; supply `--review-id` when responding from a pending review.
`threads list`	GraphQL	Enumerates review threads for the pull request.
`threads resolve` / `unresolve`	GraphQL	Mutates thread resolution via `resolveReviewThread` / `unresolveReviewThread`; supply GraphQL thread node IDs (`PRRT_…`).

Additional docs

docs/USAGE.md — Command-by-command inputs, outputs, and examples for v1.6.0.
docs/SCHEMAS.md — JSON schemas for each structured response (optional fields omitted rather than set to null).
docs/AGENTS.md — Agent-focused workflows, prompts, and best practices.

Design for LLMs & Automated Agents

gh-pr-review is designed to give LLMs and agents the exact PR review context they need — without the noisy, multi-step GitHub API workflow.

Why it's LLM-friendly

Replaces multi-call API chains with one command
Instead of calling list reviews → list thread comments → list comments,
a single gh pr-review review view command returns the entire, assembled review structure.
Deterministic, stable output
Consistent formatting, stable ordering, and predictable field names make parsing reliable for agents.
Compact, meaningful JSON
Only essential fields are returned. Low-signal metadata (URLs, hashes, unused fields) is stripped out to reduce token usage.
Pre-joined review threads
Threads come fully reconstructed with inline context — no need for agents to merge comments manually.
Server-side filters for token efficiency
Options like --unresolved and --tail help reduce payload size and keep inputs affordable for LLMs.

"A good tool definition should define a clear, narrow purpose, return exactly the meaningful context the agent needs, and avoid burdening the model with low-signal intermediate results."

Using as a Skill

gh-pr-review can be used as a reusable skill for AI coding agents via Vercel's add-skill package.

Installation as a Skill

To add gh-pr-review as a skill to your AI coding agent:

npx @vercel/add-skill https://github.com/agynio/gh-pr-review

This command will:

Install the gh-pr-review extension via gh extension install
Register the skill with your AI agent using the SKILL.md definition
Make all gh-pr-review commands available as skill actions

What the Skill Provides

Once installed, your AI coding agent can:

View PR reviews: Get complete inline comment threads with file context
Reply to comments: Respond to review feedback programmatically
Resolve threads: Mark discussions as resolved after addressing feedback
Create reviews: Start pending reviews and add inline comments
Filter intelligently: Focus on unresolved, non-outdated comments by specific reviewers

All commands return structured JSON optimized for agent consumption with minimal tokens and maximum context.

Example Agent Workflow

User: "Show me unresolved comments on PR #42" Agent: gh pr-review review view -R owner/repo --pr 42 --unresolved --not_outdated Agent: [Parses JSON, summarizes 3 unresolved threads]

User: "Reply to the comment about error handling" Agent: gh pr-review comments reply 42 -R owner/repo --thread-id PRRT_... --body "Fixed in commit abc123" Agent: gh pr-review threads resolve 42 -R owner/repo --thread-id PRRT_...

Skill Documentation

See SKILL.md for complete skill documentation including:

Core commands reference
JSON output schemas
Best practices for agents
Common workflow patterns

Development

Run the test suite and linters locally with cgo disabled (matching the release build):

CGO_ENABLED=0 go test ./...
CGO_ENABLED=0 golangci-lint run

Releases are built using the cli/gh-extension-precompile workflow to publish binaries for macOS, Linux, and Windows.

NAME

SYNOPSIS

INFO

DESCRIPTION

README