Skip to main content

cc-pr-reviewer

PyPI Downloads uv Ruff

A small Textual TUI that lists every open GitHub PR where you are a requested reviewer, and hands the selected PR off to a coding-agent CLI of your choice — Claude Code, OpenAI Codex CLI, or Google Gemini CLI — to perform the review. Claude Code uses the PR Review Toolkit plugin; Codex and Gemini load the same six review criteria as native Skills that ship with this package (cc_pr_reviewer/skills/<name>/SKILL.md), materialised into the checked-out PR workspace under .agents/skills/ for the duration of each review.

cc-pr-reviewer screenshot

What it does

  • gh search prs --review-requested=@me --state=open fetches your review queue across every repo you have access to.
  • Displays them in a scrollable table (repo, number, title, author, age, draft flag).
  • Keyboard-driven: pick a PR and press Enter to open a confirmation modal; on Enter/y it clones the repo (if needed), checks out the PR branch via gh pr checkout, and launches the selected coding-agent CLI inside that working tree with a prompt that drives a six-dimension PR review (code-quality, silent-failure hunting, type design, test coverage, comment quality, simplification opportunities). See Keybindings for the full list.
  • Three CLI backends, switchable from the TUI. Press c to cycle the global default (claude → codex → gemini → claude, persisted across sessions), or Ctrl+L inside the confirm modal to override for a single launch. Default is Claude Code.

How you use it

A bird's-eye view of a review from your side of the keyboard:

flowchart TD
    A([Launch<br/>cc-pr-reviewer]) --> B["See your PR<br/>review queue"]
    B --> C["Pick a PR<br/>+ press Enter"]
    C --> D["Confirm modal:<br/>choose CLI, agents,<br/>post-inline comments"]
    D --> E["Coding agent reviews<br/>the PR in an isolated<br/>checkout"]
    E --> F{Findings?}
    F -- "post-inline on" --> G["Comments / approval<br/>posted to the PR"]
    F -- "post-inline off" --> H["Findings shown<br/>in the session"]
    G --> I([Back to the queue])
    H --> I
    I -. "if configured" .-> S["Slack notification"]

Everything between picking a PR and the agent finishing is automated — the clone/checkout, the six-dimension review prompt, and posting results. You stay in the TUI and move to the next PR. For the full internals (modals, worktree lifecycle, telemetry, teardown), see the detailed flow diagram in docs/review-flow.md.

Prerequisites

All prerequisites are validated at startup via check_prereqs(); the TUI refuses to launch until they're satisfied.

  1. GitHub CLI — installed and logged in.

    gh auth login
    
  2. At least one coding-agent CLI on your PATH:

    • Claude Code (claude) — additionally needs the PR Review Toolkit plugin installed and enabled. Install via claude plugin install pr-review-toolkit; details at https://claude.com/plugins/pr-review-toolkit. The plugin check fires at launch time (not startup), so you can still start the TUI even if the plugin is missing — you'd just see a clear toast when you try to review with Claude. Codex/Gemini are unaffected. Reviews launch Claude with --permission-mode auto, so you need a Claude Code version that supports that mode (run claude --help and check the --permission-mode choices include auto — older builds will error at launch).
    • OpenAI Codex CLI (codex) — https://github.com/openai/codex
    • Google Gemini CLI (gemini) — https://github.com/google-gemini/gemini-cli

    Startup only requires one of the three to be installed. If the CLI you previously persisted (via c) isn't on this machine's PATH, the TUI transparently falls back to the next available one for the session and shows a warning toast. Switch the global default any time with c.

  3. git — on your PATH (used for git fetch on repeat reviews).

Install

Install from PyPI with uv or pipx:

uv tool install cc-pr-reviewer
# or
pipx install cc-pr-reviewer

Then run it from anywhere:

cc-pr-reviewer

From source (for development)

uv sync
uv run cc-pr-reviewer

Configuration

Env var Default Meaning
GH_PR_WORKSPACE ~/gh-pr-workspace Where repos are cloned for local checkout.

Clones are organised as $GH_PR_WORKSPACE/<owner>/<repo>, so a second review of the same repo reuses the existing clone and just git fetches before checking out the PR.

Per-org review standards

To add your team's review rules to every review of an org's (or one repo's) PRs, drop a markdown file in $GH_PR_WORKSPACE/.review-standards/:

$GH_PR_WORKSPACE/.review-standards/
├── <owner>.md            # every repo of <owner>
└── <owner>/
    └── <repo>.md         # one repo; replaces <owner>.md for that repo

Names match case-insensitively. The file's body is added to the review prompt (the first 6,000 characters). Optional frontmatter enables a PR-title check. Values are read literally (this is not YAML, so don't double the backslashes). Quote the regex if its leading or trailing whitespace matters:

---
title_pattern: "^[A-Z]+-\d+ \[[A-Z]+\] "
---
- Follow the PR types in CONTRIBUTION_GUIDE.md.
- Never weaken an existing test just to make a change pass.

If the title doesn't match, the agent is told to raise it in the review body, not as an inline comment. If no file exists for a repo, nothing is added. The launch line shows standards: <file> when one is in use.

Keybindings

Key Action
↑ / ↓ Move through PRs
Enter Confirm, then clone + checkout + launch the selected CLI
d View full diff
o Open PR in browser
m Toggle inclusion of PRs you authored
f Filter the list by repo (picker)
g Cycle grouping: none → repo → author → none
s Toggle sort by most recently updated
c Cycle CLI: claude → codex → gemini → claude (persisted)
r / F5 Refresh the list
u Upgrade cc-pr-reviewer via uv tool upgrade
q Quit

The c key highlights green in the footer whenever the active CLI is non-default (i.e. anything other than Claude Code).

Inside the confirmation modal: Enter / Ctrl+Y to proceed, Esc / Ctrl+N to cancel, Ctrl+T to toggle post-inline (instruct the CLI to publish the findings as inline PR review comments via gh api, grouped under one review), Ctrl+L to cycle the CLI for this launch only (without changing the global default). The post-inline toggle defaults to on each time the modal opens; the CLI defaults to whatever the global c setting currently is. The chosen values are printed before the CLI launches.

Inside the filter modal: arrow keys to move, Enter to apply the highlighted repo (or pick (any repo — clear filter) to remove the filter), r to re-fetch the unfiltered PR list and pick up repos that appeared after boot, Esc to cancel. The repo list comes from the most recent unfiltered fetch — applying a filter doesn't shrink the picker. The active filter is persisted in $GH_PR_WORKSPACE/.review_state.db and restored on the next launch.

How the launch works

When you press Enter on a row, a confirmation modal shows the target PR (repo#N + title) plus the current CLI selection. On Enter/y the TUI suspends itself and runs, in order:

gh repo clone <owner>/<repo>                      # only if not already cloned
git fetch --all --prune                           # otherwise
gh pr checkout <N> --force
<selected-cli> <auto-approve flags> "<review prompt>"

The exact CLI invocation depends on which backend is active:

CLI Command
Claude claude --permission-mode auto "<prompt>"
Codex codex --ask-for-approval never --sandbox workspace-write -c sandbox_workspace_write.network_access=true "<prompt>"
Gemini gemini --approval-mode auto_edit "<prompt>"

All three are launched in modes that minimise manual permission prompts while keeping edits scoped to the cloned PR workspace. Claude's auto mode lets its classifier auto-approve the edits and git/gh api … bash the review needs (broader than the old acceptEdits, which still prompted on every bash command); Codex and Gemini auto-accept edits as closely as each permits. For Codex, sandbox_workspace_write blocks network by default; the -c sandbox_workspace_write.network_access=true override restores it so the post-inline review path can reach GitHub via gh api.

The review prompt drives the same six review dimensions across all three CLIs:

  • Claude Code delegates to the PR Review Toolkit plugin's six sub-agents (Comment Analyzer, PR Test Analyzer, Silent Failure Hunter, Type Design Analyzer, Code Reviewer, Code Simplifier).
  • Codex and Gemini load the same six review criteria as native Skills. The bundled SKILL.md files (cc_pr_reviewer/skills/<name>/SKILL.md) are an adapted fork of the upstream toolkit's agent prompts with Codex/Gemini Skills frontmatter prepended. At launch they're copied into <workspace>/.agents/skills/<name>/SKILL.md (the cross-tool interop path both CLIs are documented to scan at session start — refs: Codex Skills, Gemini Skills) and removed on exit. Per those docs, only metadata is loaded eagerly — full instructions are pulled in on activation.

If the modal's post-inline toggle (Ctrl+T) is on, the prompt is extended to ask the CLI to publish each finding as an inline review comment via a single POST /repos/{owner}/{repo}/pulls/{n}/reviews call through gh api, so they land grouped under one review. On a re-review of someone else's PR where only P3 (nit) findings remain, the CLI is also asked to resolve any of its own previously-posted threads that the new code has addressed before submitting the APPROVE. Set Approval on others' PRs in Settings (,) to Never approve (comment only) to turn off every approve/resolve step: reviews are then always submitted as event: COMMENT, and approving stays a separate manual action.

When you exit the CLI, press Enter and the TUI returns.

Keeping the bundled review prompts in sync with upstream

The bundled cc_pr_reviewer/skills/<name>/SKILL.md files are a static fork of the PR Review Toolkit plugin's agent prompts (with Codex/Gemini Skills frontmatter prepended). To check for upstream changes:

uv run python scripts/sync_pr_review_agents.py --update-plugin

This runs claude plugin update pr-review-toolkit@claude-plugins-official first, then diffs the current upstream against a committed baseline snapshot in scripts/upstream_baseline/. Exit code is 0 if nothing changed upstream, 1 if action is needed. After triaging upstream changes into the bundled files, run --save-baseline to lock in the new upstream state. See the script's --help for additional flags (--diff, --write).

Changelog

See CHANGELOG.md for the release history.

Metadata

Release files for cc-pr-reviewer 0.20.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cc-pr-reviewer 0.20.0
File Size Uploaded Provenance Actions
cc_pr_reviewer-0.20.0.tar.gz 255.6 kB Without provenance Details for cc_pr_reviewer-0.20.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cc-pr-reviewer 0.20.0
File Interpreter ABI Platform Actions
cc_pr_reviewer-0.20.0-py3-none-any.whl Python 3 none any Details for cc_pr_reviewer-0.20.0-py3-none-any.whl

Total release size: 362.6 kB

Release files / cc_pr_reviewer-0.20.0.tar.gz

Download URL cc_pr_reviewer-0.20.0.tar.gz
Size 255.6 kB
Tags Source
SHA-256 checksum
How to use checksums
f374007e1048efbae6174a5f1af79e18411e58dedf8cb07e5a9d9ae8e66fce95
BLAKE2b-256 checksum
How to use checksums
af26c3641ce5474edcb9e504ddabf700050f9316bfb7638edcb7e23fc2ac02f0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / cc_pr_reviewer-0.20.0-py3-none-any.whl

Download URL cc_pr_reviewer-0.20.0-py3-none-any.whl
Size 107.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eda53359983aedeefa0b54ae54f1f5574395e1c7fba52889678a49c06b6b6d9a
BLAKE2b-256 checksum
How to use checksums
2baa1105f16f9b3d51ecbc23c9d2d068741a63b90bba071a4fcf73fd00b82497
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for cc-pr-reviewer 0.20.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page