| name | git-diff-browser |
| description | Use when asked to view changes, show a diff, review what changed, compare branches, or see recent commits in a rich browser interface. Supports unstaged changes, staged changes, branch comparisons, commit ranges, and live watch mode with auto-refresh. |
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
python3 diff-view.py [args]
The script will:
- Generate git diff
- Convert to HTML via diff2html
- Enrich sidebar with file tree and stats
- Open in browser automatically
Step 3: Optional AI summary
For static diffs, if you want to add an AI summary:
-
Read the git diff:
git diff [appropriate args]
-
Write a concise 2-4 sentence summary explaining the intent
-
Pass to script:
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
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):
git diff
Shows working tree changes not yet staged.
Staged changes:
git diff --staged
Shows changes in the staging area (ready to commit).
Branch comparison:
git diff main...feature
Shows changes in feature since it diverged from main.
Commit range:
git diff HEAD~3..HEAD
Shows last 3 commits worth of changes.
Single commit:
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
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
curl http://127.0.0.1:<port>/api/update
Returns JSON with current diff hash and HTML if changed.
Installation
Install diff2html-cli:
npm install -g diff2html-cli
Verify installation:
which diff2html
Troubleshooting
"diff2html: command not found"
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
