Astrotation

Visual feedback for AI coding agents on Astro sites. Annotate elements right on your dev page; agents (Claude Code etc.) receive annotations live over MCP — with the exact Astro source file:line, CSS selector, Tailwind classes and computed styles attached.

Dev-only. Nothing ships to production builds.

Why Astro-native

• file:line precision. Astro dev stamps elements with data-astro-source-file/data-astro-source-loc — annotations point at the component source line, no selector guessing.
• One process. The Astro integration hosts both the toolbar UI (Dev Toolbar app) and the MCP server inside the dev server. No separate CLI, no CORS, no extra ports to babysit.
• Live both ways. Agent finishes a fix → the pin turns red (◆ feedback, "review me") in your overlay; you resolve it green after checking. Agent asks a question → you reply in the overlay.

Install

npm install -D astrotation

// astro.config.mjs
import { defineConfig } from 'astro/config';
import astrotation from 'astrotation';

export default defineConfig({
  integrations: [astrotation()],
});

Register the MCP server once (any project, same port):

claude mcp add --transport http astrotation http://localhost:7133/mcp

Use

1. npm run dev, open the site, click the ⊕ Astrotation icon in the Astro dev toolbar.
2. Hover an element (press ↑/↓ to select its parent/child for pixel-exact targeting) → click → type a note at the ❯ prompt → Enter. Pin appears.
3. Tell your agent to check the annotations — or put it in hands-free mode: "call astrotation_watch in a loop; for each annotation: acknowledge, fix, hand back with astrotation_feedback + a summary".
4. Pins recolor live: ○ open → ◑ in progress → ◆ feedback ("done, review me"). You review the change and hit resolve in the panel (✓ green) — or reply with more notes and the agent iterates. Agent questions show in the annotation thread; reply inline. Hit clear done to tidy resolved/dismissed pins.

MCP tools

Tool	Purpose
astrotation_list	All annotations (filter by status, page)
astrotation_get	One annotation, full detail (thread, source, styles, outerHTML)
astrotation_watch	Block until new annotations/replies, return batch
astrotation_acknowledge	Mark as being worked on
astrotation_feedback	Hand a finished fix back for review, with a summary (agent's terminal action — resolving is yours, in the overlay)
astrotation_dismiss	Decline with a reason
astrotation_reply	Ask the owner a clarifying question
astrotation_clear	Bulk-remove annotations by status (default: resolved+dismissed)

Options

astrotation({
  port: 7133,                            // MCP HTTP port
  file: '.astrotation/annotations.json', // store, relative to project root
})

Add .astrotation/ to your .gitignore (session artifacts, not source).

Annotation payload

{
  "id": "a1b2c3d4",
  "page": "/", "url": "http://localhost:4321/", "viewport": "1440x900",
  "element": "p",
  "selector": "section#hero > div > p",
  "sourceFile": "src/components/Hero.astro", "sourceLoc": "49:8",
  "classes": "max-w-xs",
  "section": "Hero",                       // nearest heading — where on the page
  "role": null,                            // explicit role / aria-label if present
  "styles": "display: block; font-size: 14px; …",
  "text": "Senior product designer across…",
  "selectedText": null,
  "outerHTML": "<p class=\"max-w-xs\">Senior product designer…</p>",
  "box": { "x": 980, "y": 620, "w": 320, "h": 120 },
  "comment": "make this column wider",
  "status": "pending",
  "thread": []
}

License

MIT © Dmytro Karpushyn