FAQ

Agentation is a floating toolbar that lets you annotate web pages and generate structured feedback for AI coding agents. Click elements, select text, and copy markdown that agents can parse to find and fix issues in your codebase.

It grew out of a post by Benji Taylor exploring how to give better feedback to AI agents, and has since been packaged for anyone to use.

Screenshots lose the connection to code. When you annotate a screenshot, the AI has to guess which component you mean by "the blue button." Agentation gives agents actual selectors like .sidebar > button.primary that they can grep for in your codebase. It's the difference between "fix this" and "fix this at src/components/Button.tsx:42."

Install via npm with npm install agentation -D, then import and add the <Agentation /> component to your app. Works with React 18 and Next.js.

Yes. Run npx skills add benjitaylor/agentation in your terminal, then /agentation in Claude Code. It detects your framework, installs the package, creates a provider component, and wires it into your layout.

Agentation automatically identifies elements using class names, IDs, text content, and semantic structure. Buttons are named by their text, headings by content, images by alt text. This makes it easy for agents to grep for elements in your codebase.

Yes. On React pages, Agentation traverses the fiber tree to find the component hierarchy for each annotated element. You'll see component names like <App> <Dashboard> <Button> in tooltips and output. This helps agents find the exact component file to edit. You can configure detection mode (Filtered, Smart, All, or Off) in settings.

Yes. Select any text on the page to annotate specific content. The selected text is quoted in the output, making it easy for agents to search for exact strings in your code.

Click or press Escape to collapse the toolbar. It stays minimal until you need it again.

Yes. Click to freeze all animations on the page — CSS animations, JavaScript-driven motion, and videos all pause instantly. Unfreeze to resume exactly where things left off.

Yes. Click to choose from preset colors for annotation markers. Your preference is saved in localStorage.

By default, annotations are stored in localStorage, keyed by page pathname. They persist across page refreshes but are cleared after 7 days. With Agent Sync enabled, annotations are stored on the MCP server instead, which persists across pages and sessions.

Agent Sync connects the browser toolbar to an MCP server, enabling real-time sync between reviewers and AI agents. Annotations persist across pages and can be accessed via MCP tools. Run npx add-mcp "npx -y agentation-mcp server" to configure your agent, or npx agentation-mcp init for Claude Code specifically, then enable Agent Sync in settings.

Four formats: Compact (minimal context), Standard (balanced), Detailed (full context with bounding boxes), and Forensic (maximum detail including computed styles). Choose based on how much context your AI agent needs.

Any AI coding agent that accepts text input. The markdown output is agent-agnostic and works with Claude, GPT-4, Cursor, Copilot, and others. Just paste the copied output into your agent's chat.

With Agent Sync enabled, annotations sync to a shared server and can be accessed by multiple users or agents. Without Agent Sync, annotations are stored locally in each user's browser - you can still share by copying the markdown output.

Yes, Agentation requires React 18+ as a peer dependency. It's built as a React component to integrate seamlessly with modern React applications.

Yes. Agentation is written in TypeScript and exports full type definitions. Props like demoAnnotations and configuration options are fully typed.

Yes. Agentation is a client-side component that hydrates after page load. It works with Next.js, Remix, Astro, and other SSR/SSG frameworks without issues.

Minimal impact. Agentation only adds event listeners and renders a small toolbar. It doesn't modify your existing DOM or intercept network requests. The annotation markers are lightweight SVG overlays.

You can, but it's designed as a development tool. We recommend conditionally rendering it only in development or behind a feature flag. The toolbar is invisible to users until activated.

Currently, Agentation only annotates elements in the main document. Iframes and shadow DOM content are not accessible due to browser security restrictions.

The MCP server uses better-sqlite3 as a native dependency, which occasionally causes build or runtime issues depending on your Node.js version and platform. If you run into problems, check the better-sqlite3 troubleshooting guide for solutions.

Open an issue on GitHub. Pull requests are welcome too.