gh-llm 0.1.0

No project description provided

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

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

Quick Start

PR Reading

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

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

# Show full content for one event index
gh-llm pr event 15 --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

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

Issue Reading

gh-llm issue view 77924 --repo PaddlePaddle/Paddle
gh-llm issue timeline-expand 2 --issue 77924 --repo PaddlePaddle/Paddle
gh-llm issue event 6 --issue 77924 --repo PaddlePaddle/Paddle

Comment / Thread Actions

# Edit comment
gh-llm pr comment-edit IC_xxx --body '<new_body>' --pr 77900 --repo PaddlePaddle/Paddle
gh-llm issue comment-edit IC_xxx --body '<new_body>' --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-resolve PRRT_xxx --pr 77900 --repo PaddlePaddle/Paddle
gh-llm pr thread-unresolve PRRT_xxx --pr 77900 --repo PaddlePaddle/Paddle

PR Review Workflow

1) Start from diff hunks

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

It prints per-hunk anchor lines and ready-to-run comment/suggestion commands.

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

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

4) Submit review

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

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.
• PR description uses <pr_description>...</pr_description>.
• Issue description uses <issue_description>...</issue_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