| name | pikr |
| description | Launch a visual element picker for a running web app. Opens a Chromium browser with an inspector overlay — click any element to capture its HTML, styles, selector, and source location. Use when the user describes a UI element by appearance rather than providing code or selector context, when asked to change something visual ("make this button bigger", "fix the hero section"), or when the user says "open pikr", "pick element", "show me the page", or "which element". Also suggest when you need visual context about a running web app to make accurate changes.
|
| allowed-tools | Bash, Read |
pikr — Visual Element Picker
You have access to pikr, a CLI tool that opens a Chromium browser with an inspector overlay. The user clicks UI elements and structured context is captured for you to act on.
When to Use
- User describes a UI element by appearance ("the blue submit button", "the card on the right")
- User asks to change something visual without providing code context
- You need to understand what an element looks like or where it is in the DOM
- User explicitly asks to open pikr or pick an element
How to Use
Step 1: Determine the URL
Check the conversation for mentions of a dev server URL or port. Common patterns:
- "localhost:3000", "localhost:5173", "localhost:8080"
- Check
package.json scripts for dev, start, or serve commands to infer the port
If you can't determine the URL, ask the user:
"What URL is your dev server running on? (e.g., http://localhost:3000)"
Step 2: Launch pikr
pikr <url> &
Launch pikr in the background. It will open a Chromium window showing the app.
Tell the user:
"I've opened pikr at . Switch to the browser window, press Cmd/Ctrl+Shift+X to enter inspect mode, then click the element you want to work with."
Step 3: Read Selections
Poll the log file for new selections:
tail -1 ~/.pikr/selections.jsonl
The log file contains NDJSON (one JSON object per line). Each entry has:
sessionId — identifies this pikr sessiontimestamp — when the element was selectedurl — the page URLselector — CSS selector for the elementhtml — the element's outer HTMLancestry — parent chain (e.g., form.order-form > div.actions > [this])styles — key computed styles (background, color, font-size, etc.)component — React component name (if React plugin active, otherwise null)filePath — source file path (if React plugin active, otherwise null)
Step 4: Act on the Selection
Use the captured context to:
- Find the element in the source code using the selector, HTML content, or component/file info
- Make the requested changes
- Ask if the user wants to pick more elements or if you should proceed
Step 5: Clean Up
When done, the user closes the browser window or you can stop the background process:
kill %1 2>/dev/null
Clipboard Format
If the user pastes pikr output directly (instead of using the log file), it looks like:
pikr: div.hero > button.cta
url: http://localhost:3000/page
ancestry: section.hero > div.hero-content > [this]
<button class="cta btn-primary">Get Started</button>
styles: background-color: #2563eb; color: #fff; border-radius: 8px
Recognize text starting with pikr: as a pikr selection. The HTML is the main content between the header and styles.
Troubleshooting
- pikr not found: The user needs to install it:
npm install -g pikr
- Chrome not found: Set
PUPPETEER_EXECUTABLE_PATH or install Chrome
- No selections appearing: Remind the user to press Cmd/Ctrl+Shift+X to enter inspect mode first
