📍 Nitpick

Point at a UI bug in your running app. Get a source-located fix.

A Claude Code plugin for Next.js — with first-class BMAD-METHOD support.

Press a hotkey, circle the element that's wrong, say what's off — Nitpick captures the exact component, source line, Playwright-style locators, and an annotated screenshot, then Claude (or your BMAD dev agent) fixes each report at its source.

Quickstart · With BMAD · How it works · Live demo · Commands

---

Why Nitpick

When you build a UI with an AI coding agent, the hard part isn't fixing issues — it's describing them precisely. "The card padding looks off" makes the agent guess which card, which file, which line. Round-trips pile up.

Nitpick removes the guessing. You point at the broken element in the running app, and the agent receives the comment already mapped to a source location — with the component, the styles, Playwright-style locators, and a screenshot. Reporting and fixing stay cleanly separated.

  hotkey → circle element → comment → .nitpick/001.json + 001.png
                                              │
                  /nitpick:process  ◀──────────┘   (or routed to your BMAD dev agent)
                  Claude opens the source line and fixes it.

✨ Features

• 🎯 Inspect → source — click any element to capture its React source line, component stack, computed styles, Playwright-style locators (getByRole, getByTestId, CSS, XPath), and a cropped screenshot of each selected element (<id>-1.png, <id>-2.png, …).
• ✂️ Snip — crop a region (correct at any scroll), mark it up with Arrow / Line / Circle / Box / Pen / Text, save it as a flat annotated image.
• 🎬 Record a flow — capture clicks, field inputs (text / dropdown / radio / checkbox), and navigation across multiple screens as an ordered repro script (each step with its route and a Playwright-style locator).
• 🛠 Fix me — report a problem with Nitpick itself (typed or dictated); the agent fixes the tool, not your app.
• 🧰 Draggable toolbox, configurable hotkey (or double-tap Shift, or a click).
• 🤝 BMAD-METHOD aware — route feedback to the dev agent now, or into stories after an epic.
• 🔒 Dev-only & report-only — never runs in production, never changes your app's behavior; everything stays local in .nitpick/.

🧭 Which tool should I use?

Pick by what kind of issue you're reporting:

Tool	Reach for it when the problem is…	Ideal cases	Saves
🎯 Inspect	a specific element	Wrong color / size / spacing / font / copy on a known component; a missing or broken state; anytime you want Claude to land on the exact source line + styles. Click several elements — each is captured with its own locators and image.	001-1.png, 001-2.png, … + element metadata
✂️ Snip	a region, or how things relate	Alignment / overlap / overflow / uneven spacing between sections; hover-only or hard-to-click UI (menus, tooltips, charts, <canvas>, images); when you want to draw arrows/circles to explain it.	one flat annotated 001.png
🎬 Record	a bug that takes steps to trigger	Multi-step or cross-page flows; form validation, post-submit state, "it breaks on step 3"; behavior bugs where the path matters. Gives Claude an exact repro script.	ordered actions (no images)
🛠 Fix me	Nitpick itself	The overlay misbehaves (marquee won't drag, badge missing, save fails…). Type or dictate what's wrong; the report is flagged meta, the screenshot includes the Nitpick UI, and /nitpick:process fixes the tool instead of your app.	001.png (with the overlay visible) + tool diagnostics

💡 Pair any tool with a reference image — paste or drop one into the comment box when you have a target design/look you want the result to match.

Rule of thumb: one element → Inspect · a layout/area → Snip · a sequence → Record.

Examples

• "This Upgrade button is the wrong shade of red." → Inspect the button.
• "The hero heading and the subtext don't line up; here's the Figma." → Inspect both (or Snip the region) + paste the reference.
• "These two dashboard cards overflow their container on mobile." → Snip the region.
• "After I fill the signup form and hit Next, the error appears on the wrong field." → Record the flow.

🚀 Quickstart (Claude Code)

# 1. Add the marketplace + install (in Claude Code)
/plugin marketplace add lokkrish/nitpick
/plugin install nitpick@nitpick-tools

# 2. Scaffold the overlay into your Next.js app
/nitpick:setup
npm run dev          # (re)start your dev server
/nitpick:sanity      # optional: verify the install end-to-end in a real browser

Then, in the browser:

1. Activate: Ctrl+Shift+., double-tap Shift, or click the 📍 Nitpick badge.
2. Pick a tool — Inspect, Snip, or Record — annotate, add a comment, optionally paste a reference image, and Save.
3. Repeat; reports queue in .nitpick/.

Back in Claude Code:

/nitpick:process     # Claude views each screenshot, opens the source line, and fixes it

🤝 With BMAD-METHOD

Using BMAD? Route feedback through its agents instead of editing code directly:

/nitpick:setup-bmad  # installs a BMAD-native "nitpick" agent (v6 skill / v4 agent)
/nitpick:bmad        # triage feedback, then route it

Each item is triaged into quick-fix (handed to the dev agent now) or backlog (turned into BMAD stories with /nitpick:bmad stories <epic> once the epic is done). Verified against BMAD-METHOD v6.8.

🧠 How it works

Nitpick is two artifacts joined by a file bridge (full writeup in DESIGN.md):

Part	Where it runs	What it does
Overlay (templates/)	the browser (dev-only)	capture: hotkey, annotate, screenshot, locators
Bridge (dev API route)	your Next.js dev server	writes reports to .nitpick/*.json + images
Plugin (this repo)	Claude Code	/nitpick:* commands + skill + BMAD agent that fix the queue

Screenshots capture exactly the region you're looking at (correct at any scroll position), Record saves the action flow only (no images), and the overlay is completely inert when idle — no background work, no memory growth.

🎛 Command reference

Command	What it does
/nitpick:setup	Scaffold the overlay + dev API route into a Next.js app (App or Pages router).
/nitpick:sanity	Verify an install end-to-end — static checks + a real-browser test (four-corner selection, snip pipeline, hostile-CSS regression, API bridge).
/nitpick:process	Fix the .nitpick/ queue in Claude (defers to BMAD if detected).
/nitpick:bmad	Triage + route feedback through BMAD (triage / quick-fix / backlog / stories / status).
/nitpick:setup-bmad	Install the BMAD-native Nitpick agent.
/nitpick:remove	Reverse setup — remove overlay, route, mount, .nitpick/, and the dep.

🔒 Privacy & safety

• Local-only — feedback is written to .nitpick/ in your repo; the overlay sends nothing anywhere else.
• Dev-only — the overlay returns null and the API route returns 410 in production.
• Report-only — Nitpick never edits your app or changes its behavior; fixing is a separate, explicit step.

🗑 Uninstall

/nitpick:remove                          # remove scaffolded code from your app
/plugin uninstall nitpick@nitpick-tools  # remove the plugin from Claude Code

🛣 Roadmap

• Native HD capture (getDisplayMedia) toggle for pixel-perfect shots on huge pages.
• MCP live-push (no "go process" step).
• React SPA (Vite / CRA) bridge.
• Multi-element batches.

See CHANGELOG.md for what's shipped.

🤝 Contributing

Issues and PRs welcome — see CONTRIBUTING.md. Be kind; we follow a Code of Conduct.

📄 License

MIT © Lokeshwaran

If Nitpick saves you round-trips, please ⭐ the repo — it really helps.