git-diff-browser

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:

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:

   git diff [appropriate args]
   

2. Write a concise 2-4 sentence summary explaining the intent

3. 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
# Should output: /usr/local/bin/diff2html (or similar)

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