Metadata-Version: 2.5
Name: cc-pr-reviewer
Version: 0.20.0
Summary: Textual TUI that lists GitHub PRs awaiting your review and hands them off to Claude Code.
Project-URL: Homepage, https://github.com/jasmedia/cc-pr-reviewer
Project-URL: Repository, https://github.com/jasmedia/cc-pr-reviewer
Project-URL: Issues, https://github.com/jasmedia/cc-pr-reviewer/issues
Author-email: Jaseem <jaseem@inferxgate.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude-code,code-review,github,pull-request,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: textual>=0.60
Description-Content-Type: text/markdown

# cc-pr-reviewer

[![PyPI Downloads](https://static.pepy.tech/badge/cc-pr-reviewer)](https://pepy.tech/projects/cc-pr-reviewer)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/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](https://claude.com/plugins/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](assets/cc-reviewer.png)

## 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](#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:

```mermaid
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`](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.
   ```sh
   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

### As a global CLI (recommended)

Install from PyPI with [uv](https://docs.astral.sh/uv/) or
[pipx](https://pipx.pypa.io/):

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

Then run it from anywhere:

```sh
cc-pr-reviewer
```

### From source (for development)

```sh
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 fetch`es
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:

```markdown
---
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:

```sh
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](https://developers.openai.com/codex/skills),
  [Gemini Skills](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md))
  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](https://claude.com/plugins/pr-review-toolkit)
plugin's agent prompts (with Codex/Gemini Skills frontmatter prepended).
To check for upstream changes:

```sh
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](CHANGELOG.md) for the release history.
