git-diff-browser

# Git Diff Browser Viewer Display rich, syntax-highlighted git diffs in your browser with a collapsible file tree sidebar. ## Overview This skill generates beautiful, interactive git diffs using diff2html and opens them in your browser. It supports multiple diff modes, live-updating watch mode, and optional AI-generated summaries. The sidebar shows a file tree with change statistics, making it easy to navigate large changesets. ## When to Use - Reviewing uncommitted changes before committing - Comparing your branch to main/master - Viewing what changed in recent commits - Code review preparation - Demonstrating changes to team members - Live-monitoring changes during development (watch mode) ## Quick Reference | User Request | Command | |--------------|---------| | "show diff" / "view changes" | `python3 diff-view.py` | | "show staged changes" | `python3 diff-view.py --staged` | | "compare to main" | `python3 diff-view.py --branch main` | | "show last 3 commits" | `python3 diff-view.py --commit HEAD~3` | | "live diff" / "watch changes" | `python3 diff-view.py --watch` | | "watch diff vs main" | `python3 diff-view.py --watch --branch main` | **Requirements:** `diff2html-cli` (install: `npm i -g diff2html-cli`) ## Implementation **Note:** The `diff-view.py` script is included in this skill directory. Run it from the skill directory or use the full path to the installed skill. ### Fast Mode (Default - Static Diff) For instant, one-time diffs, run the all-in-one script directly. No need to read git files or generate JSON manually - the script handles everything. **Step 1: Determine diff arguments from user request** | User Says | Script Args | |-----------|-------------| | *(empty/no args)* | *(no args)* | | `staged` | `--staged` | | `branch <name>` | `--branch <name>` | | `commit HEAD~N` | `--commit HEAD~N` | | `commit <sha>` | `--commit <sha>` | **Step 2: Execute diff script** ```bash python3 diff-view.py [args] ``` The script will: 1. Generate git diff 2. Convert to HTML via diff2html 3. Enrich sidebar with file tree and stats 4. Open in browser automatically **Step 3: Optional AI summary** For static diffs, if you want to add an AI summary: 1. Read the git diff: ```bash git diff [appropriate args] ``` 2. Write a concise 2-4 sentence summary explaining the intent 3. Pass to script: ```bash python3 diff-view.py --summary "Your summary here" [other args] ``` The sidebar will show your summary instead of just the mechanical stats. ### Watch Mode (Live-Updating Diff) When the user requests live/continuous viewing (watch mode), the diff auto-refreshes as files change. **Step 1: Start watch server in background** ```bash python3 diff-view.py --watch [args] & ``` The script prints: ``` Serving on http://127.0.0.1:12345 (PID: 67890) Press Ctrl+C to stop, or it will auto-stop when this session ends. ``` **Step 2: Note the server URL and PID** The URL (e.g., `http://127.0.0.1:12345`) is where the live diff is served. **Step 3: Dispatch AI summary subagent (async)** While the server runs, spawn a subagent to generate the AI summary: **Subagent prompt:** ``` Generate an AI summary for the current git diff. 1. Read the diff with: git diff [appropriate args based on watch mode] 2. Write a concise 2-4 sentence summary explaining the intent of the changes 3. POST the summary to the watch server: curl -s -X POST http://127.0.0.1:<port>/api/summary \ -H 'Content-Type: application/json' \ -d '{"summary":"Your summary text here"}' The summary will appear in the browser sidebar without a page reload. ``` **Step 4: Explain watch mode behavior** Tell the user: - The page updates in-place via DOM patching (no full reload) - Scroll position is preserved across updates - Default refresh interval: 2 seconds - Server auto-stops when the Claude session exits - AI summary will appear once the subagent completes ### Diff Modes Explained **Unstaged changes (default):** ```bash git diff ``` Shows working tree changes not yet staged. **Staged changes:** ```bash git diff --staged ``` Shows changes in the staging area (ready to commit). **Branch comparison:** ```bash git diff main...feature ``` Shows changes in `feature` since it diverged from `main`. **Commit range:** ```bash git diff HEAD~3..HEAD ``` Shows last 3 commits worth of changes. **Single commit:** ```bash git show <commit-sha> ``` Shows changes in a specific commit. ### Sidebar Features The sidebar displays: - **File tree** - Collapsible directory structure - **Change stats** - Additions/deletions per file - **File status** - Modified (M), Added (A), Deleted (D), Renamed (R) - **Mechanical summary** - File count and total changes - **AI summary** - Intent and context (if provided) **Example sidebar:** ``` Current Branch → Main ━━━━━━━━━━━━━━━━━━━━━━━ Summary Refactored authentication flow to use JWT tokens instead of session cookies. Added new middleware for token validation and updated login/logout handlers. 3 files changed +187 additions -93 deletions ├─ src/ │ ├─ auth/ │ │ ├─ middleware.js [M] +125 -45 │ │ └─ tokens.js [A] +42 -0 │ └─ handlers/ │ └─ login.js [M] +20 -48 ``` ### Watch Mode API The watch server exposes a JSON API: **POST /api/summary** - Update AI summary ```bash curl -X POST http://127.0.0.1:<port>/api/summary \ -H 'Content-Type: application/json' \ -d '{"summary":"New summary text"}' ``` **GET /api/update** - Poll for diff changes ```bash curl http://127.0.0.1:<port>/api/update ``` Returns JSON with current diff hash and HTML if changed. ## Installation **Install diff2html-cli:** ```bash npm install -g diff2html-cli ``` **Verify installation:** ```bash which diff2html # Should output: /usr/local/bin/diff2html (or similar) ``` ## Troubleshooting **"diff2html: command not found"** ```bash npm install -g diff2html-cli ``` **Empty diff shown:** - Check if there are actually changes: `git status` - For branch comparison, ensure branches exist: `git branch -a` - For commits, verify reference: `git log` **Watch mode not updating:** - Check server is running: Look for process with PID printed at startup - Verify port is accessible: `curl http://127.0.0.1:<port>` - Check for file changes: `git status` **Browser doesn't open:** - Server still runs, manually visit `http://127.0.0.1:<port>` - Check `$BROWSER` environment variable - Try setting: `export BROWSER=open` (macOS) or `export BROWSER=xdg-open` (Linux) ## Platform Notes This skill works with: - **Claude Code**: Direct execution via Bash tool, Agent for subagents - **Gemini CLI**: Use bash/subagent equivalents - **Codex**: Use RunBash/SubAgent equivalents **Dependencies:** - Python 3 (built-in on most systems) - diff2html-cli (npm install -g diff2html-cli) - Git (standard) The `diff-view.py` script is platform-independent (standard Python 3 libraries). ## Related Skills - **git-commit** - Commit changes after review - **git-pr** - Create pull request from reviewed changes - **code-review** - Structured code review process