Point at it. Your agent finds the code.

Describing a pixel to a language model is the slow part.

You can see the problem instantly. Communicating it costs three paragraphs, two screenshots and a round of “which button?”. Your agent then greps for a class name that turned out to be generated at build time.

earmark removes the translation step. You point; it captures the things a machine can act on. Everything it reports is verified before it is reported: a selector is checked against the document until it resolves to exactly one element, and a source line is checked against the live DOM before it is claimed.

Two lines to mount it.

earmark ships as plain ESM with no build step of its own. Mount it behind a development guard so it never reaches production.

// main.js: anywhere that runs once, in development
import { createEarmark } from 'earmark'

if (import.meta.env.DEV) createEarmark()

With no bundler at all

<script type="module" src="/node_modules/earmark/src/index.js" data-earmark-auto></script>

Options

createEarmark({
  endpoint: 'http://127.0.0.1:7331',  // or false for copy-paste only
  hotkey:   'alt+a',
  theme:    'auto',                    // 'auto' | 'light' | 'dark'
  persist:  true,                      // keep annotations across reloads
  onAnnotate: (annotation) => {},
})

TypeScript

Every package ships hand-written declarations. The domain types live in earmark and are re-exported by the broker and the MCP server, so an annotation is the same type on both sides of the wire.

import { createEarmark, type Annotation } from 'earmark'

const pending: Annotation[] = createEarmark().annotations

Five tools, bottom right.

Press alt+a or click the arrow to start picking. ⌘↵ saves an annotation, esc cancels.

Priority

Each annotation is high, normal or low. High sorts first when the agent lists them, so an agent working top-down hits the urgent items before the nits.

Copy-paste, or let the agent read directly.

Copy-paste mode needs no infrastructure at all: click Copy markdown and paste into your agent. Agent-sync mode runs a local broker so the agent reads annotations itself, asks questions, and reports back.

The fix loop, once MCP is connected

Three ways to find the line, in order of confidence.

A selector tells an agent what to grep for. A file and line tells it where to look: the difference between one edit and three searches. earmark tries each tier and reports which one produced the answer.

Vite

// vite.config.js
import earmark from 'vite-plugin-earmark'

export default { plugins: [react(), earmark()] }

Covers .jsx, .tsx and .svelte. The Svelte markup is stamped before the compiler sees it, so SvelteKit needs nothing extra.

Next.js

// next.config.mjs
import { withEarmark } from 'earmark-loader/next'

export default withEarmark({})

A pre-loader for webpack and Turbopack rather than a Babel plugin, because adding Babel would switch the project off SWC and slow every build down. Both compilations are stamped, client and server: React hydration will not add an attribute the server HTML did not have.

Iframes and canvas

A same-origin iframe is picked like anything else: the annotation names the frame, its document, and a selector that resolves inside it. A canvas has no DOM, so rather than pretend, it reports the coordinate space its drawing code works in.

- **Inside iframe:** `#preview` (preview)
  - frame document: /examples/frames/child.html

- **Canvas:**
  - buffer 640×360, CSS 320×180 (2× / 2× per CSS pixel, dpr 2)
  - clicked at buffer pixel (354, 200)

Plain HTML and CSS

Nothing to configure. Every CSS rule that actually matches the element is mapped back to the file and line that declares it, including rules inside a <style> block, which are offset into their host document rather than reported against a phantom file.

- **Source:** `index.html:101:11` _(resolved from the served HTML)_
- **CSS rules that style it:**
  - `button` → index.html (inline <style>):49
    - padding: 7px 13px; border-radius: 8px;
  - `button.primary` → index.html (inline <style>):59
    - background: var(--accent); color: rgb(255, 255, 255);

Eleven tools, one process.

The MCP server runs the annotation store, the endpoint your browser talks to, and the stdio transport in a single process. There is no second daemon to keep alive.

claude mcp add earmark -- npx -y earmark-mcp

# or write it into the project's .mcp.json
npx earmark-mcp init

When something is not working, ask it why

$ npx earmark-mcp doctor

✓ Node version: v24.12.0
✓ sqlite backend: available
✓ MCP registration: earmark is registered in .mcp.json
✓ Broker: responding on http://127.0.0.1:7331 (1 annotations, 2 sessions)
✓ Browser overlay: http://localhost:5173/ (1 annotations)

Everything checks out.

Each failing check prints the command that fixes it, and the exit code is non-zero, so it works in CI.

A session is one tab, not one page load.

The session id lives in sessionStorage, so refreshing does not fragment your feedback into three sessions. Each annotation still carries its own URL: a tab that wandered across /dashboard, /settings and /billing gives the agent one group with three differently-routed items.

• Client-side navigation is tracked. pushState, replaceState, popstate and hashchange all update the session’s route list.
• A tab counts as connected for exactly as long as its event stream is open. No heartbeat protocol to get wrong.
• Reconnecting merges rather than overwrites. If the agent replied while the tab was closed, that reply survives the reconnect.

Runs standalone, if you would rather not use MCP.

npx earmark-server --port 7331
curl http://127.0.0.1:7331/markdown

A development tool, scoped like one.

• The broker binds 127.0.0.1 only. Do not bind it to 0.0.0.0.
• CORS is open by design: your dev server lives on an arbitrary origin. Any page in your browser can reach a loopback port, so pass --token if that matters on your machine.
• Source resolution re-fetches your own page and stylesheets from the same origin. Nothing is sent anywhere.
• Webhooks are the exception: they send page URLs, element text and whatever you typed off the machine. Only configure endpoints you control.
• Do not run it on a shared or public host.

What it does not do.

Stated plainly, because finding out later is worse than knowing now.

• Touch works, small screens are not the target. Picking, dragging a region and the whole panel respond to touch, and the controls grow for a fingertip. It is still a tool for looking at your app on a machine you develop on.
• No screenshots, on purpose. Your agent already drives a browser, and it is handed a verified selector and a URL, so it can capture the element itself at full fidelity. A bundled screenshot library would send a re-render of the page rather than what the browser painted.
• Cross-origin iframes stay invisible. Same-origin frames are pickable: you get the element, the frame that holds it, and a selector that resolves inside that frame. A cross-origin frame is a browser security boundary, not a gap to work around.
• Canvas and WebGL have no DOM to annotate. What you get instead is the coordinate space the drawing code works in: the clicked pixel in the canvas buffer, the buffer size against the CSS box, the ratio between them, the context type and the detected renderer.
• Closed shadow roots are opaque. Open ones are picked into and reported with the expression that reaches them. A root created with mode: 'closed' exposes nothing to any script, so the component itself is what gets annotated.
• Nothing inside a shadow root or a canvas has a source line. That markup is created by script and its styles never appear in the document's stylesheets, so there is no file to walk.
• Version 0.1.x. All six packages are on npm and the whole surface is tested, but nothing here has been through a second pair of hands yet.