# pi-diff

Local, full-screen branch diff browser, built as a [Pi](https://github.com/earendil-works) extension.
Runs inside your existing Pi session — no forge, no network call, no mouse required.

```
/diff           # compare current branch against auto-detected base (origin/HEAD, else main/master)
/diff develop   # compare against an explicit base branch
/diff local     # compare HEAD with staged, unstaged, and untracked working-tree changes
```

Branch mode uses `git diff <base>...HEAD` (the same merge-base semantics as GitHub/GitLab
PR/MR views). Local mode compares the final working tree against `HEAD`, combining staged
and unstaged edits and adding non-ignored untracked files as new-file diffs.

## What it does

- Two-pane layout: file tree on the left (status, +/-, viewed marker), diff on the right.
- Syntax-highlighted diff content powered by `@shikijs/cli` — the same Shiki ANSI engine used by `pi-claude-style-tools`. It selects `github-dark`/`github-light` from Pi's active surface, caches highlighted old/new streams so multiline grammar state remains correct, and normalizes low-contrast tokens over tinted diff rows.
- Fast keyboard scrolling: full page, half page, hunk jumps, and top/bottom jumps — no need to walk large diffs one line at a time.
- **Viewed tracking that survives restarts.** Marking a file viewed is keyed on that file's
  diff content hash and persisted in the session (branch-aware, like Pi's built-in Todo list).
  If you amend/rebase and a file's diff actually changes, it's automatically un-marked.
- Draft comments anchored to a specific line. `r` writes them all out to
  `.pi-diff/<branch>.md` — easy to paste into a PR/MR description or hand to a reviewer.

## Keybindings

| Key | Tree focus | Diff focus |
|---|---|---|
| `↑`/`↓` or `j`/`k` | move file selection | move line cursor |
| `→` / `l` / `Tab` | switch to diff pane | — |
| `←` / `h` / `Tab` | — | switch to file tree |
| `PageDown` / `PageUp` | move one page | move one page |
| `d` / `i` | move half a page down / up | move half a page down / up |
| `]` / `[` | — | next/previous hunk |
| `g` / `G` | first/last file | first/last changed line |
| `Space` | toggle viewed | toggle viewed (current file) |
| `Enter` | toggle viewed + advance | draft a comment at cursor |
| `c` | — | draft a comment at cursor |
| `n` / `N` | jump to next/previous **unviewed** file | same |
| `r` | write drafted comments to `.pi-diff/<branch>.md` | same |
| `q` / `Esc` | close panel | same |

## Known limitations (v0.2)

- `/diff local` shows the final working-tree state rather than separate staged and unstaged
  snapshots. Ignored files are intentionally excluded.
- No mouse support — deliberate. Pi's TUI component API doesn't expose a mouse event layer,
  and the rest of Pi is keyboard-driven; fighting that would cost more than it's worth.
- Comments are local notes, not posted anywhere automatically — there's no forge in the loop.

## Local development

```
npm install            # installs the pinned @shikijs/cli renderer dependency
npm test               # parser + git/local mode + tree + Shiki theme + panel tests
pi -e ./index.ts        # load this extension for a single session, from any git repo
```

## Install

```
pi install ~/code/pi-diff                              # current local checkout, all sessions
pi install -l ~/code/pi-diff                           # current local checkout, this project only
pi install git:git@github.com:j-joker/pi-diffffff.git # private GitHub repository (SSH access required)
```

From npm after publication: `pi install npm:pi-diffffff`.