gh-llm 0.1.12

🤖 CLI tooling for LLM-first GitHub reading and review workflows.

gh-llm

CLI tooling for LLM-first GitHub reading and review workflows.

Core Goal

gh-llm is primarily built to help an LLM quickly capture the same key context a human reviewer would get on GitHub Web, and provide actionable next commands at exactly the right places.

Key Ideas

• Timeline-first rendering: merge comments, reviews, commits, labels, references, force-push, and state changes into one ordered stream that mirrors GitHub Web reading.
• Real cursor pagination: use GitHub GraphQL first/after and last/before, so page expansion always pulls real server-side data instead of fake local slicing.
• Progressive context loading: show first + last page first (high-signal summary), then expand hidden pages/events only when needed.
• Action-oriented output: place ready-to-run gh / gh-llm commands at decision points (expand, view detail, reply, resolve, review).
• Stateless interaction model: no fragile local session state required between commands.

Requirements

• Python 3.14+
• gh installed and authenticated (gh auth status)

Install

As CLI (recommended)

uv tool install gh-llm
gh-llm --help

As gh extension

gh extension install ShigureLab/gh-llm
gh llm --help

The extension entrypoint forwards to local repository path via uv run --project <extension_repo_path> gh-llm .... gh llm ... and gh-llm ... are equivalent command surfaces.

Install Skill

If you want the reusable GitHub conversation skill, install it directly from this repo:

npx skills add https://github.com/ShigureLab/gh-llm --skill github-conversation

Quick Start

PR Reading

# Show first + last timeline pages with actionable hints
gh-llm pr view 77900 --repo PaddlePaddle/Paddle
gh llm pr view 77900 --repo PaddlePaddle/Paddle

# Show selected regions only
gh-llm pr view 77900 --repo PaddlePaddle/Paddle --show timeline,checks

# Expand one hidden timeline page
gh-llm pr timeline-expand 2 --pr 77900 --repo PaddlePaddle/Paddle

# Auto-expand folded content in default/timeline view
gh-llm pr view 77900 --repo PaddlePaddle/Paddle --expand resolved,minimized
gh-llm pr timeline-expand 2 --pr 77900 --repo PaddlePaddle/Paddle --expand all

# Show full content for one comment node id
gh-llm pr comment-expand IC_xxx --pr 77900 --repo PaddlePaddle/Paddle

# Expand resolved review details in batch
gh-llm pr review-expand PRR_xxx,PRR_yyy --pr 77900 --repo PaddlePaddle/Paddle
# Expand only a conversation range (e.g. hidden middle part)
gh-llm pr review-expand PRR_xxx --threads 6-16 --pr 77900 --repo PaddlePaddle/Paddle

# Checks
gh-llm pr checks --pr 77900 --repo PaddlePaddle/Paddle
gh-llm pr checks --pr 77900 --repo PaddlePaddle/Paddle --all

# Detect conflicted files on demand (for conflicted PRs)
gh-llm pr conflict-files --pr 77971 --repo PaddlePaddle/Paddle

PR Body Scaffold

# Load the repo PR template (when present), append required sections, and write a body file
# The command also prints a ready-to-run `gh pr create --body-file ...` command.
gh-llm pr body-template --repo ShigureLab/watchfs --title 'feat: add watcher summary'

gh-llm pr body-template \
  --repo ShigureLab/watchfs \
  --requirements 'Motivation,Validation,Related Issues' \
  --output /tmp/pr_body.md

If the repo has no PR template, gh-llm falls back to a simple editable scaffold. The bundled skills/github-conversation/SKILL.md also documents this workflow for skill users.

Issue Reading

gh-llm issue view 77924 --repo PaddlePaddle/Paddle
gh-llm issue timeline-expand 2 --issue 77924 --repo PaddlePaddle/Paddle
gh-llm issue comment-expand IC_xxx --issue 77924 --repo PaddlePaddle/Paddle
gh-llm issue view 77924 --repo PaddlePaddle/Paddle --expand minimized,details
gh-llm issue view 77924 --repo PaddlePaddle/Paddle --show meta,description

When --show does not include timeline (for example --show meta, --show summary, or --show actions), both pr view and issue view stay on the lightweight metadata path and skip timeline bootstrap.

--expand values:

• PR: resolved, minimized, details, all
• Issue: minimized, details, all
• Supports comma-separated values and repeated flags.

--show values:

• PR: meta, description, timeline, checks, actions, mergeability, all
• Issue: meta, description, timeline, actions, all
• Supports comma-separated values and repeated flags.
• summary is supported as an alias for meta,description.

Comment / Thread Actions

# Edit comment
gh-llm pr comment-edit IC_xxx --body '<new_body>' --pr 77900 --repo PaddlePaddle/Paddle
gh-llm pr comment-edit IC_xxx --body-file edit.md --pr 77900 --repo PaddlePaddle/Paddle
gh-llm issue comment-edit IC_xxx --body '<new_body>' --issue 77924 --repo PaddlePaddle/Paddle
gh-llm issue comment-edit IC_xxx --body-file edit.md --issue 77924 --repo PaddlePaddle/Paddle

# Reply / resolve / unresolve review thread
gh-llm pr thread-reply PRRT_xxx --body '<reply>' --pr 77900 --repo PaddlePaddle/Paddle
gh-llm pr thread-reply PRRT_xxx --body-file reply.md --pr 77900 --repo PaddlePaddle/Paddle
cat reply.md | gh-llm pr thread-reply PRRT_xxx --body-file - --pr 77900 --repo PaddlePaddle/Paddle
gh-llm pr thread-resolve PRRT_xxx --pr 77900 --repo PaddlePaddle/Paddle
gh-llm pr thread-unresolve PRRT_xxx --pr 77900 --repo PaddlePaddle/Paddle

Environment Diagnosis

gh-llm doctor
gh llm doctor

doctor prints the current entrypoint, resolved executable paths, gh / gh-llm versions, active-host gh auth status, a REST probe, a minimal GraphQL probe, and proxy-related environment variables.

When gh-llm hits transport errors such as GraphQL EOF / timeout failures, the CLI now reports the retry count and suggests concrete follow-up commands such as gh auth status, gh api graphql -f query='query{viewer{login}}', and gh-llm doctor.

PR Review Workflow

1) Start from diff hunks

gh-llm pr review-start --pr 77938 --repo PaddlePaddle/Paddle

# Large PRs: load the next changed-file page
gh-llm pr review-start --pr 78255 --repo PaddlePaddle/Paddle --page 2 --page-size 5

# Jump to an absolute changed-file range directly
gh-llm pr review-start --pr 78255 --repo PaddlePaddle/Paddle --files 6-12

# Add extra unchanged context around each hunk
gh-llm pr review-start --pr 77938 --repo PaddlePaddle/Paddle --context-lines 3

# Focus one changed file directly
gh-llm pr review-start --pr 78255 --repo PaddlePaddle/Paddle --path 'paddle/phi/api/include/compat/ATen/core/TensorBody.h'

# Show only selected hunks inside that file
gh-llm pr review-start --pr 78255 --repo PaddlePaddle/Paddle --path 'TensorBody.h' --hunks 2-3

# Reuse a pinned head snapshot when loading another page
gh-llm pr review-start --pr 78255 --repo PaddlePaddle/Paddle --page 2 --page-size 5 --head <head_sha>

It prints changed-file page summary, existing review-thread summaries with lightweight comment previews inline on matching diff lines when possible, per-hunk commentable LEFT/RIGHT line ranges, numbered diff lines, and ready-to-run comment/suggestion commands. Generated follow-up commands reuse --head <head_sha> automatically so pagination and inline review commands stay on the same PR snapshot; stale snapshots are rejected with a refresh hint. Use --context-lines <n> when the GitHub patch hunk is too tight and you need a small amount of extra unchanged code around it.

2) Add inline comment

gh-llm pr review-comment \
  --path 'paddle/phi/api/include/compat/torch/library.h' \
  --line 106 \
  --side RIGHT \
  --body 'Please add a regression test for duplicate keyword arguments.' \
  --pr 77938 --repo PaddlePaddle/Paddle

gh-llm pr review-comment \
  --path 'paddle/phi/api/include/compat/torch/library.h' \
  --line 106 \
  --side RIGHT \
  --body-file review-comment.md \
  --pr 77938 --repo PaddlePaddle/Paddle

3) Add inline suggestion

gh-llm pr review-suggest \
  --path 'path/to/file' \
  --line 123 \
  --side RIGHT \
  --body 'Suggested update' \
  --suggestion 'replacement_code_here' \
  --pr 77938 --repo PaddlePaddle/Paddle

gh-llm pr review-suggest \
  --path 'path/to/file' \
  --line 123 \
  --side RIGHT \
  --body-file suggestion-reason.md \
  --suggestion 'replacement_code_here' \
  --pr 77938 --repo PaddlePaddle/Paddle

gh-llm pr review-suggest \
  --path 'path/to/file' \
  --line 123 \
  --side RIGHT \
  --body-file suggestion-reason.md \
  --suggestion-file replacement.txt \
  --pr 77938 --repo PaddlePaddle/Paddle

4) Submit review

gh-llm pr review-submit \
  --event COMMENT \
  --body 'Overall feedback...' \
  --pr 77938 --repo PaddlePaddle/Paddle

gh-llm pr review-submit \
  --event REQUEST_CHANGES \
  --body-file review.md \
  --pr 77938 --repo PaddlePaddle/Paddle

pr comment-edit, issue comment-edit, thread-reply, review-comment, review-suggest, and review-submit all support --body-file - to read multi-line text from standard input. review-suggest also supports --suggestion-file - for the suggestion block itself.

Note: review-suggest --body-file - --suggestion-file - is intentionally rejected because standard input can only be consumed once. Use separate files when both the reason text and suggestion block need external input.

Submit behavior:

• If you already have a pending review on this PR, review-submit submits that pending review.
• Otherwise, it creates and submits a new review.

This supports the normal flow where one review contains multiple inline comments.

Render Conventions

• PR/Issue metadata is rendered as frontmatter.
• Description uses <description>...</description>.
• Comment body uses <comment>...</comment> to avoid markdown fence ambiguity.
• Hidden timeline sections are separated by --- and include expand commands.

Development

uv run ruff check
uv run pyright
uv run pytest -q

License

MIT