diffprism 0.44.0 → 0.47.0

package/README.md

@@ -1,30 +1,97 @@
 # DiffPrism
 
-Your AI writes code — you need to review it before it ships. But terminal diffs
-are hard to read, and there's no way to leave structured feedback that the agent
-actually acts on.
-
-DiffPrism opens a code review UI in your browser with syntax-highlighted diffs,
-inline commenting, and structured decisions (approve / request changes) that
-Claude reads and responds to.
+Review GitHub PRs with AI superpowers. Paste a PR URL, see the diff in your browser, and use Claude Code or Cursor to interrogate every line, file, and change. Your AI gets full codebase context from your local clone — not just the diff hunks.
 
 ## How It Works
 
-1. Type `/review` in Claude Code — your browser opens with the diff
-2. Review the changes, leave inline comments, approve or request changes
-3. Claude reads your decision and acts on it (commits, opens a PR, or fixes what you flagged)
+1. **Open a PR** — `diffprism review https://github.com/owner/repo/pull/123`
+2. **See the diff** — Browser opens with syntax-highlighted diffs, file browser, and analysis briefing
+3. **Ask your AI** — In Claude Code or Cursor, ask questions about the changes. Your AI calls MCP tools to get context and posts findings inline on the diff.
+
+```
+$ cd ~/dev/my-project
+$ diffprism review https://github.com/owner/repo/pull/123
+  Fetching PR #123 from owner/repo...
+  Add retry logic to API client
+  4 files changed
+  Local repo: /Users/you/dev/my-project
+
+  Review open in browser. Use Claude Code to ask questions about this PR.
+```
+
+Then in Claude Code:
+
+```
+> What does this PR change?
+  → calls get_pr_context → high-level overview
+
+> Is the retry logic in client.ts correct?
+  → calls get_file_diff + get_file_context → full file from your local clone
+
+> Flag line 47 as a concern
+  → calls add_review_comment → annotation appears on the diff in your browser
+```
 
-## Setup for Claude Code
+## Setup
 
 ```bash
-npx diffprism setup
+npm install -g diffprism
+diffprism setup          # Register MCP server with Claude Code
 ```
 
-Configures everything and opens a demo review so you can see it in action. Restart Claude Code afterward to load the MCP server.
+Run the server from within your local clone so the AI gets full file context:
 
-## Use from the CLI
+```bash
+cd ~/dev/my-project
+diffprism server         # Or let it auto-start on first review
+```
 
-No setup needed — just run:
+## PR Review
+
+```bash
+diffprism review https://github.com/owner/repo/pull/123   # Full GitHub URL
+diffprism review owner/repo#123                            # Shorthand format
+```
+
+The server auto-detects your local clone by matching `git remote -v` against the PR's repo. Your AI can then read full files via `git show` — not just diff hunks.
+
+## MCP Tools
+
+DiffPrism exposes 14 MCP tools to your AI:
+
+### PR Review
+| Tool | Purpose |
+|------|---------|
+| `get_pr_context` | High-level PR overview: metadata, briefing, file list, local repo status |
+| `get_file_diff` | Diff hunks for a specific file with triage category |
+| `get_file_context` | Full file content from local repo via `git show` |
+| `add_review_comment` | Post a comment that appears inline on the diff in real-time |
+| `get_review_comments` | Read all comments and annotations on the session |
+| `get_user_focus` | What file/line the user is currently viewing in the browser |
+
+### Review Lifecycle
+| Tool | Purpose |
+|------|---------|
+| `open_review` | Open browser review UI for local changes or a GitHub PR |
+| `get_review_result` | Fetch result from a previous review |
+| `update_review_context` | Push updated reasoning/description to a running session |
+
+### Analysis
+| Tool | Purpose |
+|------|---------|
+| `analyze_diff` | Returns analysis JSON (patterns, complexity, test gaps) |
+| `get_diff` | Returns structured diff JSON (file-level and hunk-level changes) |
+
+### Annotation
+| Tool | Purpose |
+|------|---------|
+| `add_annotation` | Post a structured finding on a specific line |
+| `flag_for_attention` | Mark files for human attention |
+| `get_review_state` | Get current state of a session including all annotations |
+
+## Local Agent Review
+
+DiffPrism also works for reviewing local agent-generated changes:
 
 ```bash
 diffprism review                    # Review all changes (staged + unstaged)
@@ -33,35 +100,68 @@ diffprism review HEAD~3             # Last 3 commits
 diffprism review main..feature      # Branch diff
 ```
 
-## Multi-Agent Reviews
+Running multiple Claude Code sessions? All reviews appear in one browser dashboard with status badges, branch info, and desktop notifications.
 
-Running multiple Claude Code sessions (e.g., in git worktrees)? All reviews appear in one browser tab.
+## Commit Gate
 
-The server starts automatically on first use — no manual setup needed. Each review shows up as a session with status badges, branch info, and change stats. Click to switch between reviews. Desktop notifications alert you when new reviews arrive.
+Review is only reliable if something other than memory triggers it. `diffprism hook`
+wires the review into your pre-commit hook, so a substantial change opens a review
+before it can land.
 
 ```bash
-diffprism server status             # Check if server is running
-diffprism server stop               # Stop the background server
+diffprism hook install              # Add the gate to this repo's pre-commit hook
+diffprism hook uninstall            # Remove it
 ```
 
+By default a staged diff of **120+ changed lines** opens a review; anything smaller
+commits untouched. A gate that stops every commit is one you learn to skip with
+`--no-verify`, and a skipped gate is worse than none. Tune it per repo:
+
+```bash
+git config diffprism.gate-lines 200
+```
+
+Approve and the commit proceeds. Request changes and the commit is blocked — with
+your comments printed in the output, so the agent that ran `git commit` can read
+what you asked for and fix it without another round trip:
+
+```
+140 staged lines (gate at 120) — opening DiffPrism review...
+
+  feature.ts:12  [must_fix]  these should be a single exported record
+  feature.ts:88  [question]  is this range meant to be inclusive?
+
+Commit blocked: the review requested changes.
+```
+
+Install adds one line between markers, so uninstall removes exactly that and leaves
+the rest of your hook alone. Repos using `core.hooksPath` are handled.
+
 ## Features
 
-- **Syntax-highlighted diffs** — unified or split (side-by-side) view
-- **Inline commenting** — click any line to add `must_fix`, `suggestion`, `question`, or `nitpick` comments
-- **Review briefing** — complexity scores, test coverage gaps, pattern flags, dependency tracking
-- **Agent reasoning panel** — see why the AI made each change
-- **Quick actions** — Approve & Commit or Approve, Commit & PR from the review UI
-- **Multi-session dashboard** — review multiple agents from one browser tab
-- **Desktop notifications** — get alerted when a new review arrives
-- **GitHub PR review** — review any GitHub PR in DiffPrism's UI
-- **Keyboard shortcuts** — `j`/`k` files, `n`/`p` hunks, `c` comment, `s` status, `?` help
-- **Dark/light mode** — toggle with persistence
+- **AI-powered PR review** — Your AI gets full codebase context via 14 MCP tools
+- **Live annotations** — AI findings appear inline on the diff in real-time
+- **Local repo context** — Full file content from your clone, not just diff hunks
+- **No vendor lock-in** — Works with Claude Code, Cursor, or any MCP client
+- **Syntax-highlighted diffs** — Unified or split view with refractor
+- **Multi-session dashboard** — Review multiple agents from one browser tab
+- **Review briefing** — Complexity scores, test coverage gaps, pattern flags
+- **Auto-detect local repo** — Matches `git remote -v` against the PR's repo
+- **Keyboard shortcuts** — `j`/`k` files, `n`/`p` hunks, `s` status, `?` help
+- **Dark/light mode** — Toggle with persistence
 
-## Uninstall
+## CLI Reference
 
 ```bash
-npx diffprism teardown              # Remove from current project
-npx diffprism teardown --global     # Remove global config
+diffprism review <ref>              # Open a review (PR URL, git ref, or flags)
+diffprism setup                     # Configure Claude Code integration
+diffprism setup --global            # Global setup (no git repo needed)
+diffprism server                    # Start the background server
+diffprism server status             # Check server status
+diffprism server stop               # Stop the server
+diffprism hook install              # Gate commits on a review
+diffprism hook uninstall            # Remove the gate
+diffprism teardown                  # Remove configuration
 ```
 
 ## Development
@@ -82,7 +182,7 @@ packages/core       — Server, types, server-client utilities
 packages/git        — Git diff extraction + parser
 packages/analysis   — Deterministic review briefing
 packages/ui         — React 19 + Vite 6 + Tailwind + Zustand
-packages/mcp-server — MCP tool server (9 tools)
+packages/mcp-server — MCP tool server (14 tools)
 packages/github     — GitHub PR fetching + review submission
 cli/                — Commander CLI
 ```