# pi-diff-review

A full-screen **git diff reviewer** for the [Pi coding agent](https://pi.dev), with
vim keybindings and inline comments. Review Pi's changes the way
you'd review a pull request, then send all your comments back to Pi as a
single structured code-review message.

![pi-diff-review demo](assets/demo.gif)

```
/diff              review changes vs HEAD
/diff HEAD~3       review against an arbitrary git ref
/diff --staged     review staged changes only
```

Anything after `/diff` is passed straight through to `git diff`.

## Features

- **Vim-style navigation** — move by line, half-page, file, or hunk.
- **Inline comments** — attach a note to any line; it renders right beneath the code.
- **Visual range comments** — select a span of lines and comment on the whole block.
- **Structured hand-off** — on send, comments are grouped by file and delivered to the
  agent as a Markdown review message so it can address each one.
- **Theme-aware rendering** — colors follow your active Pi theme.

## Install

Requires Pi. Install from npm:

```bash
pi install npm:@johnfodero/pi-diff-review
```

Or install from git (pin to a released version):

```bash
pi install git:github.com/JohnFodero/pi-diff-review@v1.0.0
```

Try it for a single session without installing:

```bash
pi -e npm:@johnfodero/pi-diff-review
```

Then run `/diff` inside an interactive (TUI) Pi session in any git repository.

## Keybindings

| Key | Action |
| --- | --- |
| `j` / `k` or `↓` / `↑` | Move cursor down / up |
| `Ctrl+d` / `Ctrl+u` | Half-page down / up |
| `g` / `G` | Jump to top / bottom |
| `n` / `N` | Next / previous file |
| `}` / `{` | Next / previous hunk |
| `v` | Visual mode: select a line range, then `c` to comment it |
| `c` | Comment on the current line |
| `d` | Delete comment on the current line |
| `Enter` or `:w` | Send all comments to the agent |
| `q` or `Esc` | Quit without sending |

## How it works

`/diff` runs a plain unified `git diff` (bypassing pagers and external diff drivers
like delta/difftastic), parses it into navigable rows while tracking real line
numbers, and renders it in a full-screen TUI component. Comments are keyed to lines
and, on send, grouped by file into a Markdown message delivered to the agent — as a
follow-up message if the agent is busy, or immediately if idle.

## What gets sent to the agent

Only the lines you commented on — **never the whole diff.** The full diff you scroll
through stays local to the viewer and never enters the model's context. On send, each
comment becomes one Markdown list item under its file header, containing a precise line
reference (`file:line (+/-)` or `file:lo-hi`), the code itself, and your note:

```markdown
Code review feedback on `git diff HEAD` (2 comments). Please address each:

### src/auth.ts
- **src/auth.ts:42 (+)** `const token = req.headers.authorization`
  This should validate the Bearer prefix before slicing.
```

Visual-range comments emit the selected span in a fenced code block instead of inline.

This keeps the hand-off **prompt-efficient**: token cost scales with the number of
comments, not the size of the diff — reviewing a 3,000-line change and leaving two
comments sends only those two lines plus your notes. The tradeoff is that the agent
sees just the commented line, not its surrounding context; when it needs more, it
reads the file on demand rather than having a large diff preloaded into context.

## Requirements

- Pi running in interactive (TUI) mode — `/diff` is a no-op in print/RPC modes.
- `git` on your `PATH`, run from within a git repository.

## License

MIT © John Fodero