Agentic PR monitoring for GitHub
Interactive TUI for humans, structured output for AI agents

Install · Quick Start · How It Works · Commands · Global Flags · Agent Integration · Agent Skill · Development

Install

Requires GitHub CLI (gh) v2.0+.

gh extension install indrasvat/gh-ghent

Quick Start

# See unresolved review threads
gh ghent comments --pr 42

# Check CI status
gh ghent checks --pr 42

# Full PR dashboard with merge readiness
gh ghent status --pr 42

How It Works

ghent detects your environment automatically:

• TTY (interactive terminal) — launches a Bubble Tea TUI with keyboard navigation, tabs, and expandable views
• Piped / --no-tui — outputs structured data (JSON by default) for scripts and AI agents

No configuration needed. Authentication is inherited from gh auth.

Commands

gh ghent comments

Show unresolved review threads for a PR.

gh ghent comments --pr 42                    # Interactive TUI
gh ghent comments --pr 42 --format json      # JSON for agents
gh ghent comments --pr 42 --format json | jq '.unresolved_count'

Flag	Description
--pr	Pull request number (required)

Exit codes: 0 = no unresolved threads, 1 = has unresolved threads.

gh ghent checks

Show CI check runs, status, and annotations.

gh ghent checks --pr 42                      # Interactive TUI
gh ghent checks --pr 42 --logs               # Include error logs
gh ghent checks --pr 42 --watch              # Poll until complete
gh ghent checks --pr 42 --format json | jq '.overall_status'

Flag	Description
--pr	Pull request number (required)
--logs	Include failing job log excerpts in output
--watch	Poll until all checks complete, fail-fast on failure

Exit codes: 0 = all pass, 1 = failure, 3 = pending.

gh ghent resolve

Resolve or unresolve review threads.

gh ghent resolve --pr 42 --thread PRRT_abc123        # Single thread
gh ghent resolve --pr 42 --all                        # All threads
gh ghent resolve --pr 42 --thread PRRT_abc123 --unresolve  # Reopen

Flag	Description
--pr	Pull request number (required)
--thread	Thread ID to resolve (PRRT_... node ID)
--all	Resolve all unresolved threads
--unresolve	Unresolve instead of resolve

Exit codes: 0 = all success / no-op success, 1 = partial failure, 2 = total failure.

gh ghent reply

Reply to a review thread. Designed for AI agent use.

gh ghent reply --pr 42 --thread PRRT_abc123 --body "Fixed in latest commit"
gh ghent reply --pr 42 --thread PRRT_abc123 --body-file response.md
echo "Acknowledged" | gh ghent reply --pr 42 --thread PRRT_abc123 --body-file -

Flag	Description
--pr	Pull request number (required)
--thread	Thread ID to reply to (required)
--body	Reply body text (supports markdown)
--body-file	Read reply body from file (- for stdin)

Exit codes: 0 = reply posted, 1 = thread not found, 2 = error.

gh ghent dismiss

Dismiss stale blocking reviews that are no longer about the current PR head.

gh ghent dismiss --pr 42 --dry-run
gh ghent dismiss --pr 42 --bots-only --message "superseded by current HEAD"
gh ghent dismiss --pr 42 --review PRR_kwDO... --message "superseded by current HEAD"

This command is intentionally narrow:

• only CHANGES_REQUESTED reviews
• only when the review commit is stale relative to the current PR head
• never current reviews

Flag	Description
--pr	Pull request number (required)
--review	Review node ID or numeric review ID to dismiss
--author	Limit to one review author
--bots-only	Limit to stale blocking bot reviews
--message	Dismissal message sent to GitHub (required unless --dry-run)
--dry-run	Preview matching stale blockers without dismissing

Exit codes: 0 = all success, 1 = partial failure, 2 = total failure.

gh ghent status

Combined PR status dashboard with merge-readiness assessment.

gh ghent status --pr 42                     # Interactive dashboard
gh ghent status --pr 42 --logs --format json  # Full status with failure diagnostics
gh ghent status --pr 42 --watch --format json # Wait for CI, then full report
gh ghent status --pr 42 --await-review        # Wait for CI + bounded review stabilization
gh ghent status --pr 42 --quiet               # Silent merge-readiness gate
gh ghent status --pr 42 --solo                # Skip approval check (personal repos)
gh ghent status --pr 42 --format json | jq '.stale_reviews'

Flag	Description
--pr	Pull request number (required)
--logs	Include failing job log excerpts and annotations
--watch	Poll until CI completes, then output full status
--await-review	After CI completes, wait for bounded review stabilization (implies --watch)
--review-timeout	Hard timeout for --await-review (default: 5m)
--quiet	Silent on merge-ready (exit 0), full output on not-ready (exit 1)
--compact	One-line-per-thread compact digest for agents
--solo	Skip approval requirement for single-maintainer repos

Merge-ready when: no unresolved threads + all checks pass + at least one approval. With --solo, the approval requirement is skipped (but CHANGES_REQUESTED still blocks). Stale CHANGES_REQUESTED reviews still block until explicitly dismissed. status surfaces them in stale_reviews and suggests a safe gh ghent dismiss command.

Exit codes: 0 = merge-ready, 1 = not merge-ready.

Global Flags

These flags work with all commands:

Flag	Short	Description	Default
--repo	-R	Repository in OWNER/REPO format	current repo
--format	-f	Output format: json, md, xml	json
--no-tui		Force pipe mode even in TTY	false
--verbose		Show additional context	false
--debug		Debug logging to stderr	false
--solo		Skip approval requirement (GH_GHENT_SOLO=1)	false
--pr		Pull request number

Agent Integration

ghent is built for AI coding agents. Use --no-tui --format json for reliable structured output.

JSON Output

# Get unresolved threads with IDs for resolution
gh ghent comments --pr 42 --format json --no-tui

# Check CI and get failure details
gh ghent checks --pr 42 --format json --logs --no-tui

# One-shot merge readiness
gh ghent status --pr 42 --format json --no-tui | jq '.is_merge_ready'

# Surface stale blocking reviews
gh ghent status --pr 42 --format json --no-tui | jq '.stale_reviews'

Exit Codes

All commands use meaningful exit codes for scripting:

Code	Meaning
0	Success / pass / merge-ready
1	Action needed (unresolved threads, check failure, not merge-ready)
2	Error (API failure, auth, permissions)
3	Pending (checks still running)

For dismiss, exit 0 also covers the safe no-op case where no stale blockers matched. Exit 1 means partial dismissal failure and exit 2 means every attempted dismissal failed.

Agent Workflow Example

# 1. Use the single blessed review command
STATUS=$(gh ghent status --pr 42 --await-review --logs --format json --no-tui)

# 2. Fix CI failures if present
echo "$STATUS" | jq '.checks.checks[] | select(.conclusion=="failure") | {name, log_excerpt, annotations}'

# 3. Read unresolved review threads
echo "$STATUS" | jq '.comments.threads[] | {id, path, line, body: .comments[0].body}'

# 4. Fix code, then resolve + reply as needed
gh ghent resolve --pr 42 --all --format json

# 5. After pushing fixes, run the same command again
STATUS=$(gh ghent status --pr 42 --await-review --logs --format json --no-tui)

# 6. If stale blockers exist, dismiss only those stale blockers
echo "$STATUS" | jq '.stale_reviews'
gh ghent dismiss --pr 42 --bots-only --message "superseded by current HEAD"

# 7. Stop only when merge-ready and review_monitor is not low-confidence
echo "$STATUS" | jq '{merge_ready: .is_merge_ready, stale_reviews: .stale_reviews, review_monitor: .review_monitor}'

Output Formats

JSON (default) — machine-readable, works with jq:

gh ghent checks --pr 42 --format json

Markdown — human-readable piped output:

gh ghent comments --pr 42 --format md

XML — structured markup:

gh ghent checks --pr 42 --format xml

For AI Agents (Agent Skill)

ghent ships an Agent Skill so AI coding agents (Claude Code, Codex, Cursor, Cline, Copilot, Amp, etc.) can discover and use it automatically.

npx skills add indrasvat/gh-ghent

The skill teaches agents when and how to use ghent — triggering conditions, pipe-mode commands, JSON output parsing, exit code branching, and complete review-fix-resolve workflows. See skill/SKILL.md for the full skill content.

Development

make build     # Build binary
make test      # Run tests
make lint      # Run linter
make ci        # Full CI check (lint + test + vet)
make install   # Build and register as gh extension

License

MIT