comparing-branches-visually

name	comparing-branches-visually
description	Check out two branches in separate worktrees, start both dev servers on different ports, screenshot the same pages, and produce a visual diff.
user-invocable	true

Comparing Branches Visually

Create a visual before/after comparison of UI changes between two branches.

Workflow

1. Set Up Two Worktrees

Use best-of-n-runner subagents or git worktrees to run both branches simultaneously:

# Create a worktree for the base branch
git worktree add /tmp/branch-compare-base main

# The current working directory has the feature branch

2. Start Both Servers

Start the base branch server on a different port:

# In the base worktree
cd /tmp/branch-compare-base && PORT=3001 npm run dev

# Current branch is already on the default port (3000)

3. Identify Pages to Compare

Determine which pages are affected by the changes:

git diff main --name-only | grep -E '\.(tsx?|jsx?|vue|svelte|css)'

Map changed files to their routes (e.g. app/dashboard/page.tsx → /dashboard).

4. Screenshot Both Versions

For each affected page:

1. browser_navigate to http://localhost:3001/<page> (base branch)
2. browser_take_screenshot → save as "before"
3. browser_navigate to http://localhost:3000/<page> (feature branch)
4. browser_take_screenshot → save as "after"

5. Report

Present the comparison:

Visual Diff: feature/redesign-header vs main

/dashboard:
  Before: [screenshot from main]
  After:  [screenshot from feature branch]
  Changes: Header height reduced, nav links repositioned, new avatar dropdown

/settings:
  Before: [screenshot]
  After:  [screenshot]
  Changes: No visual differences detected

6. Clean Up

# Stop the base branch server
# Remove the worktree
git worktree remove /tmp/branch-compare-base

Tips

• Test at a consistent viewport size (1280×800 is a good default)
• For mobile-first changes, also compare at 375px width
• If the app requires auth, log in on both ports first
• This pairs well with screenshotting-changelog for PR descriptions