PR Review with gh-agent

Works from any directory — everything is fetched from GitHub API.

Install gh-agent

brew install ataraxy-labs/tap/gh-agent

Requires GITHUB_TOKEN env var or GitHub CLI authenticated via gh auth login .

Workflow

1. Triage → gh-agent pr view --repo OWNER/REPO N --smart

Categorizes changes into MECHANICAL (skip), NEW LOGIC (read), BEHAVIORAL (verify inline).

2. Diffs → gh-agent pr diff --repo OWNER/REPO N --smart-files

Gets diffs for non-mechanical files only. Lock/generated/minified files excluded by default.

3. Impact analysis — after reading diffs, search for breakage outside the PR:

Identify removed/renamed exports, changed signatures, deleted types, or modified public APIs from the diff. Then search --repo-wide for each:

Find callers of a removed/renamed symbol

gh-agent pr grep --repo OWNER/REPO N --pattern "removedFunction" --repo-wide

Find references to a deleted type or enum variant

gh-agent pr grep --repo OWNER/REPO N --pattern "DeletedTypeName" --repo-wide

Find consumers of a changed interface/config

gh-agent pr grep --repo OWNER/REPO N --pattern "changedOption" --repo-wide --path src/

Structural search for removed prop usage

gh-agent pr ast-grep --repo OWNER/REPO N --pattern 'oldPropName={$$$}' --repo-wide

Search for:

• Deleted exports/types — still imported elsewhere?

• Removed function parameters — callers updated?

• Changed constants/config — validators, serializers, tests in sync?

• Removed attributes/flags — renderers, parsers, importers still reference them?

4. Context — when diffs or impact results need more detail:

Read full file at PR branch

gh-agent pr file --repo OWNER/REPO N --path PATH

Search PR changed files (fast, default)

gh-agent pr grep --repo OWNER/REPO N --pattern "functionName" gh-agent pr ast-grep --repo OWNER/REPO N --pattern 'useCallback($$$)'

--repo-wide uses GitHub Code Search + always includes PR files at head ref. PR results win on overlap. --base searches the base branch instead.

5. Review — you are an expert senior engineer with deep knowledge of software engineering best practices, security, performance, and maintainability. Perform a thorough code review of the collected diffs and impact results:

• Generate a high-level summary of the changes in the diff.

• Go file-by-file and review each changed hunk.

• Comment on what changed in that hunk (including the line range) and how it relates to other changed hunks and code, reading any other relevant files. Also call out bugs, hackiness, unnecessary code, or too much shared mutable state.

• Flag any --repo-wide hits from impact analysis that indicate broken callers, stale references, or missing updates outside the PR.

• Categorize findings by severity: CRITICAL, HIGH, MEDIUM, LOW.

6. Post (only when user asks):

Post comments (line must appear in diff — use --json to check)

gh-agent pr review --repo OWNER/REPO N --comments-file /tmp/review.json gh-agent pr diff --repo OWNER/REPO N --json # commentable lines map

Post suggestion

gh-agent pr suggest --repo OWNER/REPO N --file F --line-start S --line-end E --replacement "code"

Commands

Command Purpose

pr view --repo R N --smart

Smart triage — always start here

pr view --repo R N --json

PR metadata as JSON

pr diff --repo R N --smart-files

Diffs for non-mechanical files only

pr diff --repo R N --file F

Diff for specific file(s) (substring match, repeatable)

pr diff --repo R N --stat

File stat table

pr diff --repo R N --json

Commentable lines map

pr file --repo R N --path P

Read file at PR branch

pr grep --repo R N -p PAT

Text search PR changed files

pr grep --repo R N -p PAT --repo-wide

Text search full codebase

pr ast-grep --repo R N -p PAT

Structural search PR changed files

pr ast-grep --repo R N -p PAT --repo-wide

Structural search full codebase

pr review --repo R N -c F

Post review from JSON

pr suggest --repo R N ...

Post suggestion comment

Rules

• --smart first. Never read all diffs blindly.

• --smart-files for diffs. One call, no manual file list.

• Skip MECHANICAL. Don't read or comment on them.

• NEVER use local files. Always use pr file , pr grep , or pr ast-grep .

• Always do impact analysis. After reading diffs, --repo-wide grep for every deleted/renamed export, removed type, and changed public API. This catches broken callers outside the PR.

• Search incrementally. PR files first → --repo-wide only if needed for additional context.

• Review in-skill. Do not hand off to external review tools. Summarize, go hunk-by-hunk, flag bugs and stale references, and categorize by severity.

• Post only when asked. Present findings in chat; user decides when to post.