PixelPick

Visual UI inspector for Claude Code. Cmd+Shift+Click on any element in your browser and Claude Code automatically knows which component you're referring to.

Why PixelPick?

Stop wasting time describing UI elements to Claude Code ("the blue button in the top right corner"). Just point and click -- Claude Code will automatically see what you selected.

You: *Cmd+Shift+Click on a button*
You: "make the hover transition smoother"
Claude: *already knows which button, its file location, and current styles*

Installation

1. Install the Chrome Extension

Load the extension from node_modules/pixelpick/dist/chrome-mv3/:

1. Open chrome://extensions
2. Enable Developer mode (toggle in top right)
3. Click Load unpacked
4. Select node_modules/pixelpick/dist/chrome-mv3/

2. Set Up Claude Code Integration

npx pixelpick@latest init

This registers the MCP server and installs the auto-injection hook. Done.

Usage

1. Run your app in Chrome (localhost only)

   npm run dev  # or your dev command

2. Select elements with Cmd+Shift+Click (Mac) or Ctrl+Shift+Click (Windows/Linux)

   • Select multiple elements (up to 10) -- they accumulate automatically
   • View your selections in the extension's side panel
   • Remove individual selections or clear all

3. Switch to Claude Code and describe what you want to change

   "make this button's padding bigger"
   "change the color to blue"
   "add a loading spinner"

4. Claude automatically sees all selected elements' context

   • Selections are auto-cleared after being injected into your prompt

What Gets Captured

For React Components

• Component name (e.g., TestButton)
• Props with values
• File location with line:column (e.g., src/components/Button.tsx:24:5)
• Component tree (parent > child hierarchy)

For Any Element

• CSS selector
• Computed styles (colors, spacing, typography, etc.)
• Tailwind classes (auto-detected)
• Accessibility info (role, aria-label, etc.)
• Bounding box (position and size)

Framework Support

| Framework | Status | Component Detection | File Location | Props | |-----------|--------|---------------------|---------------|-------| | React 18 | Full Support | Yes | Yes (line + column) | Yes | | React 19 | Supported | Yes | Partial (line only) | Yes | | Non-framework | Supported | - | - | - | | Vue, Svelte | Coming Soon | - | - | - |

React 19 Note

React 19 removed precise source location metadata (_debugSource). File locations will show line number only (no column). This is a React limitation, not a PixelPick issue.

Commands

# Setup (one-time)
npx pixelpick init            # Register with Claude Code
npx pixelpick init --project  # Use project scope

# Server management
npx pixelpick start           # Start MCP server manually
npx pixelpick status          # Check connection status

# Help
npx pixelpick help            # Show all commands
npx pixelpick --version       # Show version

How It Works

PixelPick uses a three-component architecture:

Chrome Extension  <--WebSocket-->  MCP Server  <--MCP+Hook-->  Claude Code
  (Element UI)                  (Selection Buffer)             (AI Assistant)

1. Chrome Extension: Captures element selections via Cmd+Shift+Click, detects React components, maintains multi-selection list, sends via WebSocket
2. MCP Server: Maintains selection buffer (up to 10 active + 50 history), exposes MCP tools, runs WebSocket + IPC servers
3. UserPromptSubmit Hook: Automatically injects all active selections on every prompt (deterministic, <500ms), auto-clears after injection

Why This Approach?

• Zero-config: npx pixelpick init sets up everything automatically
• Deterministic: Hook fires on EVERY prompt (doesn't rely on Claude deciding to call a tool)
• Framework-aware: Extracts React component names, props, and file locations from Fiber internals
• Localhost-only: Security-focused, never runs on production URLs
• Fast: Hook checks selection in <500ms via HTTP IPC endpoint

Troubleshooting

Extension shows "disconnected" (yellow badge)

npx pixelpick status

If server not running:

• Make sure you have a Claude Code session running (MCP servers start with Claude)
• Or manually start: npx pixelpick start

Selection not appearing in Claude Code

Check hook is installed:

cat ~/.claude/settings.json | grep pixelpick

Re-run setup if missing:

npx pixelpick init

Port already in use

Check what's using the port:

lsof -i :9315

Use different port:

PIXELPICK_PORT=9999 npx pixelpick start

React component name not detected

Possible causes:

• Not a React app (PixelPick will fall back to CSS selector)
• Minified production build (component names are stripped)
• React DevTools disabled (check React Fiber is accessible)

Debug:

// In browser console
$0  // Selected element
Object.keys($0).find(k => k.startsWith('__reactFiber'))  // Should return fiber key

File location missing (React 19)

This is expected. React 19 removed _debugSource metadata. PixelPick will fall back to stack trace parsing, which provides line numbers only (no column).

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | PIXELPICK_PORT | 9315 | WebSocket server port | | PIXELPICK_IPC_PORT | 9316 | HTTP IPC server port (for hook) |

Security

PixelPick only runs on localhost (127.0.0.1 and localhost). It will never activate on production websites.

The Chrome extension requests only two permissions:

• alarms: Keep WebSocket alive (MV3 service workers suspend)
• sidePanel: Display selection list in Chrome's side panel

Content scripts are declared in the manifest and only match localhost and 127.0.0.1.

No data is sent to external servers. Everything runs locally. See PRIVACY.md for the full privacy policy.

Advanced Usage

Activate Picker Programmatically

Use the pick_element MCP tool:

You: "activate the element picker"
Claude: *calls pick_element tool*
You: *clicks on element in browser*

Access Selection History

You: "show me the last 5 elements I selected"
Claude: *calls get_selection_history tool*

Clear Selections

You: "clear all selections"
Claude: *calls clear_selection tool*

Note: Selections are automatically cleared after being injected into your prompt, so manual clearing is rarely needed.

Contributing

Issues and PRs welcome at GitHub.

License

MIT - see LICENSE for details.

Made for developers who ship fast. Stop describing, start pointing.