see-my-clicks

Alt+Click any element in the browser to capture its info for your AI coding assistant.

Click elements, optionally add a comment describing what's wrong, then tell your AI to "check my clicks".

Works with Claude Code, Codex CLI, Cursor, Windsurf, and GitHub Copilot.

Install

npm install -D see-my-clicks

Setup

Vite

1. Add the plugin to your Vite config:

// vite.config.js
import { seeMyClicks } from 'see-my-clicks'

export default defineConfig({
  plugins: [seeMyClicks()]
})

SvelteKit

SvelteKit bypasses Vite's transformIndexHtml hook, so the plugin can't inject the client script automatically. The CLI handles this — just run npx see-my-clicks init and it will patch src/app.html with the script tag.

If you prefer to do it manually, add to src/app.html:

<script src="/__see-my-clicks/client.js"></script>

The Vite plugin is still needed for the middleware (seeMyClicks() in your Vite config).

Universal (any dev server)

Works with Express, Webpack dev server, Next.js, or anything that supports connect-style middleware.

1. Add the middleware to your dev server:

// Express
import express from 'express'
import { createMiddleware } from 'see-my-clicks'

const app = express()
app.use(createMiddleware())

// Webpack devServer (webpack.config.js)
const { createMiddleware } = require('see-my-clicks')

module.exports = {
  devServer: {
    setupMiddlewares(middlewares, devServer) {
      devServer.app.use(createMiddleware())
      return middlewares
    }
  }
}

2. Add the script tag to your HTML:

<script src="/__see-my-clicks/client.js"></script>

The middleware serves the client script automatically at this URL — no bundler plugin needed.

AI tool instructions

Install the instruction file for your AI tool:

npx see-my-clicks init claude       # Claude Code
npx see-my-clicks init codex        # Codex CLI
npx see-my-clicks init cursor       # Cursor
npx see-my-clicks init windsurf     # Windsurf
npx see-my-clicks init copilot      # GitHub Copilot
npx see-my-clicks init all          # all of the above

You can also pass multiple: npx see-my-clicks init claude cursor

| Tool | What gets created | |---|---| | Claude Code | .claude/commands/clicked.md (slash command) | | Codex CLI | Section appended to AGENTS.md | | Cursor | .cursor/rules/see-my-clicks.mdc | | Windsurf | Section appended to .windsurfrules | | GitHub Copilot | Section appended to .github/copilot-instructions.md |

(Optional) Choose what happens with your clicks

By default, your AI suggests code fixes. You can change this with --action:

npx see-my-clicks init claude --action=github-issues
npx see-my-clicks init all --action=just-report

| Action | What it does | |---|---| | suggest-fixes | Suggest code fixes based on clicks and comments (default) | | github-issues | Create GitHub issues via gh CLI | | just-report | Just show what was clicked, take no action |

You can also edit the generated instruction file directly — the action is in a clearly marked <!-- action:start/end --> section.

Use it

• Run your dev server
• Alt+Click any element in the browser — a comment modal appears showing which element you clicked
• Add an optional comment describing what should change, or press Esc to cancel
• A purple badge in the corner shows your capture count — click it to review, manage, or delete captures
• Use the + New Session button in the review panel to start a named session
• Use the purge button (🗑) in the review panel to clear all click data
• Tell your AI to "check my clicks" (or run /clicked in Claude Code)
• After your AI retrieves clicks, markers dim automatically to show they've been seen — the next Alt+Click starts a fresh session
• Use the ↺ button in the review panel to mark all clicks as unread again

How it works

• A small script is injected into your page during development (via Vite plugin or script tag)
• Hover with Alt held to see a highlight with a tooltip showing the element tag and component name
• Alt+Click captures the element's tag, selector, text, bounding box, attributes, and framework component info
• Captured elements get numbered purple markers so you can see what you've annotated
• Clicks are saved to .see-my-clicks/clicked.json via a local dev server endpoint, grouped into sessions
• Your AI retrieves new clicks via npx see-my-clicks retrieve — a read marker ensures each click is only returned once

Sessions

Clicks are organized into sessions — named groups of related captures.

• Your first Alt+Click auto-creates a default session
• Use the + New Session button in the review panel to start a named session (e.g. "Header fixes", "Mobile layout")
• When your AI processes clicks, it sees them grouped by session, making it easier to understand context
• After your AI retrieves clicks, the next Alt+Click automatically starts a new session — no manual action needed

Framework detection

The plugin automatically detects components from:

• Svelte — via __svelte_meta (dev mode) and svelte-* class hashes
• React — via __reactFiber$ fiber tree walk (finds nearest named component)
• Vue 2/3 — via __vue__ / __vueParentComponent

Component name and source file are included in the capture when available.

Options

seeMyClicks({
  outputFile: '.see-my-clicks/clicked.json',   // output path relative to cwd
  modifier: 'alt',                              // 'alt' (default), 'ctrl', or 'meta'
})

The modifier option changes the key used for capture clicks. Use 'ctrl' on Linux (where Alt+Click may be captured by the window manager) or 'meta' to use Cmd on macOS.

CLI commands

npx see-my-clicks retrieve   # Get new clicks since last retrieve (JSON to stdout)
npx see-my-clicks purge       # Delete all click data and reset the read marker
npx see-my-clicks init [...]  # Install AI tool instructions

The retrieve command uses a read marker — each call returns only clicks captured since the previous retrieve, so clicks are never lost or duplicated.

Keyboard shortcuts

| Action | Shortcut | |---|---| | Capture element | Alt+Click | | Save comment | Enter | | Cancel capture | Esc | | Multiline comment | Shift+Enter | | Undo last click | Ctrl+Alt+Z (Cmd+Alt+Z on Mac) |

UI features

• Highlight tooltip — when hovering with Alt held, shows the element tag and component name
• Click counter badge — persistent purple badge showing capture count; click to expand the review panel
• Review panel — lists all captures grouped by session, with delete buttons for each item
• Element markers — numbered purple dots on captured elements so you can see what's been annotated; click a marker to edit its comment. Markers dim after your AI retrieves them to indicate they've been seen
• ↺ Mark unread button — appears in the review panel after a retrieve; resets the read state so all markers become active again
• Element info in modal — the comment modal shows which element you clicked (tag, text, component)

Regression test

There is a Playwright regression for the modal resize-close bug:

npm run test:regression

It verifies both behaviors:

• resizing/drag-like interaction that starts inside the modal must not close it
• a normal outside click should still close it

License

MIT