Metadata-Version: 2.4
Name: diffbutler
Version: 0.6.1
Summary: A terminal dashboard for human-directed AI code reviews.
Keywords: code-review,github,terminal,ai
License-Expression: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Dist: aiosqlite>=0.22.1
Requires-Dist: alembic>=1.19.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.13.5
Requires-Dist: pydantic-settings>=2.15.0
Requires-Dist: rich>=15.0.0
Requires-Dist: sqlalchemy[asyncio]>=2.0.52
Requires-Dist: textual>=8.2.8
Requires-Dist: tomlkit>=0.15.1
Requires-Dist: typer>=0.27.2
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# DiffButler

A terminal dashboard for human-directed AI code reviews on GitHub.

Keep track of what each pull request needs next: AI review, your review, or author
changes. Start an AI review, discuss its findings in the agent's own session, and
finish your review in the browser.

![DiffButler dashboard showing pull requests and the next review action](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/diffbutler.png)

## Install

Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and Git, then
install DiffButler from [PyPI](https://pypi.org/project/diffbutler/):

```sh
uv tool install --python 3.14 diffbutler
```

uv manages Python and dependencies in an isolated environment. No virtual environment
activation is needed. If `diffbutler` is not on your PATH, run `uv tool update-shell`
and restart your shell.

To upgrade a PyPI installation:

```sh
uv tool upgrade diffbutler
```

To install from a local checkout of this repository instead, run from its root:

```sh
uv tool install --python 3.14 .
```

Install and sign in to Codex CLI or Claude Code before requesting AI reviews.
The native presets support Codex CLI or Claude Code on Linux and macOS without version checks.
Reviews use your normal agent settings, including model and reasoning effort, with
background permission and output overrides. New conversations remain in the agent’s
own history after DiffButler cleans up its workspaces; existing private sessions
retain their original home for resume.
See [supported agents and validation](docs/native-reviews.md) for details.

## Use

Use authenticated GitHub access, including for public repositories. If you already
use `gh auth login`, export its token before launching DiffButler:

```sh
export GITHUB_TOKEN="$(gh auth token)"
```

Alternatively, create a [fine-grained personal access token](https://github.com/settings/personal-access-tokens)
for the repositories you want to review with **Pull requests: Read-only** permission,
and set it as `GITHUB_TOKEN`. Anonymous access is a last resort for public repositories;
its low API quota makes it unsuitable for regular polling. See the
[authentication guide](docs/github.md#authentication-options) for host/account selection,
HTTPS versus SSH Git setup, and token permissions.

From the GitHub repository you want to review, launch:

```sh
diffbutler
```

First-run setup detects the local repository and asks whether to monitor just that
repository or all repositories belonging to the same owner. It looks up your GitHub
username using the selected token, asks for your preferred agent, and saves your choices.
If username detection is unavailable, setup asks for it. Choose the recommended token
access for public repositories; private repositories require it. Setup asks for the
token's environment variable name and validates access. It never saves the token.
New configs silently enable both Codex and Claude when found in `PATH`; setup asks
only which detected agent should be the default. Missing agents get commented-out
entries you can enable after installation.
Later launches reuse your configuration.
Repository filters accept exact names such as `heikkitoivonen/diffbutler` or
`heikkitoivonen/*` for all accessible repositories owned by that account.

The dashboard shows active reviews, including followed PRs whose GitHub review
requests have disappeared after you posted feedback. Waiting-for-author reviews
stay visible across refreshes and restarts. If an approved PR receives new commits,
it reappears as `done+` at the end of the queue without starting another AI review.
Polling spreads API quota evenly until it resets, leaving 10% in reserve: it slows
when quota is scarce or refreshes are costly and speeds back up when quota recovers.

Select a PR with the arrow keys, then work through the review:

1. Optionally press `n` to change the current configured AI reviewer for all PRs.
   Press `r` to start a background AI review. Reviews start only when you request them.
   The agent is instructed to read the PR description, discussion, and earlier review
   threads and replies before reviewing the local code, reporting any unavailable context.
   DiffButler caches full Git history and reviews changes from the PR merge base
   to its head, excluding unrelated changes made later on the target branch.
2. A successful review shows `approve` only when the AI explicitly reports no findings;
   otherwise it shows `check`. Press `Enter` to read the results, or `c` to resume
   the saved agent conversation.
   If the agent exits normally but DiffButler cannot parse its output, the task also
   shows `check`; use `c` to inspect the saved conversation or `L` for captured output.
   Changing reviewers leaves that conversation available through `c`; pressing `r`
   starts a new run with the current reviewer and replaces the current review details.
   Ask questions and explicitly tell the agent which comments to post, if any.
3. Exit the agent to return to the dashboard, which refreshes activity from GitHub.
   Press `o` to open the PR in your browser at any time; it does not change the state.
   Press `w` if you are waiting for author changes, or `a` once you are ready to approve.
4. After approving on GitHub, press `m` to mark the task complete locally. DiffButler
   also detects your approval, closure, or merge and cleans up owned session resources
   while retaining review history.

`Space` performs the selected PR's next action: start a review, discuss findings,
or open the browser. For `check` and `author`, it resumes the saved agent conversation,
just like `c`. An AI review never counts as your approval. Background analysis
uses the agent's [native permission controls](docs/native-reviews.md#native-permissions-and-authentication)
and read-only review instructions; source sent to the agent may go to its model provider.

- `/`: Filter the queue.
- `A`: Toggle monitoring all open PRs in configured repositories.
- `b`: Browse accessible PRs and follow one.
- `R`: Find and add a PR by link or number, then review it; choose a repository if
  the number is ambiguous. Explicitly selected PRs bypass queue visibility filters.
- `Ctrl+R`: Refresh from GitHub.
- `k`: Stop the selected PR's review and reset its local tracking and owned resources.
  It disappears until a forge refresh rediscovers it; review history is retained.
- `h`: View completed review history.
- `?`: Show all keyboard shortcuts.
- `q`: Quit.

See the [dashboard guide](docs/dashboard.md) for all actions and
[configuration guide](docs/configuration.md) for settings.

Your own PRs are hidden from the review queue by default, including direct and team
requests. Use `R` to select one explicitly, or set `include_own_prs = true` in `[ui]`
to show them all, such as PRs an agent created using your account.
PRs assigned to you are also hidden by default, even when
you are requested directly or through a team. Set `include_assigned_prs = true` in
`[ui]` to include them, or select one with `R`.

### How PRs move through the board

Solid arrows are actions you take; dashed arrows happen automatically.

How a PR arrives:

![Flow diagram: review requests and all-PR monitoring reach the board through polling, browsing adds followed PRs, and your own or assigned PRs are hidden unless enabled; R adds a PR directly and starts a review. New PRs start as pending unless already approved, closed, or merged.](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/docs/diagrams/pr-arrival.svg)

How its status changes:

![State diagram: r queues a review, the worker runs it, and the result is approve or check; w, a, and m move a PR between author, approve, and done; Ctrl+C or a failed agent returns it to pending; GitHub commits, your submitted reviews, and closes or merges move it automatically; new commits after approval show done+.](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/docs/diagrams/pr-status.svg)

`r`, `a`, `w`, and `m` work from any open status, not only along the arrows shown,
though `r` refuses while a review is already queued or running. New commits on a
`done+` PR keep it `done+` rather than returning it to `pending`.

How it leaves:

![Flow diagram: m, your approval, or a close or merge moves a PR to done and history; k removes it until a refresh finds it still requested or monitored; becoming an assignee hides it unless include_assigned_prs is set or it was selected with R.](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/docs/diagrams/pr-exit.svg)

A PR stays on the board when its review request is withdrawn; press `k` to remove it.
A PR you only followed stays away after `k` until you follow it again.

## Reset

Close running DiffButler sessions, then run:

```sh
diffbutler reset
```

DiffButler refuses a second command or dashboard using the same data home, including
`reset`, while another instance is running. Its instance lock releases on process
exit; a leftover PID file does not block startup. See the
[locking details](docs/configuration.md#single-instance) before handling Git lock files
or resetting after a crash.

After confirmation, this permanently removes DiffButler's standard configuration,
data, and state directories, including review history, saved sessions, and diagnostic
logs. Custom files outside those directories are preserved. Use `diffbutler reset --force`
to skip confirmation. Run `diffbutler` again to repeat first-run setup.

## Uninstall

Remove the uv-installed command and its isolated environment:

```sh
uv tool uninstall diffbutler
```

This keeps your DiffButler configuration, review history, and diagnostic logs.
To remove those too, run `diffbutler reset` **before uninstalling**; see
[Reset](#reset) for what it deletes.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks.

## License

[MIT](LICENSE.txt).
