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 the happy-path packages with npm install -D @alexgorbatchev/agentation @alexgorbatchev/agentation-cli @alexgorbatchev/pi-agentation, mount <Agentation projectId="my-project" /> behind a NODE_ENV check, then run npx agentation start, npm run dev, and npx pi-agentation. Only projectId is required on <Agentation />; the rest of the props are optional for the standard local workflow.

There is no maintained Claude Code-specific one-command setup in this fork. The happy path for automation is Pi: install @alexgorbatchev/pi-agentation alongside Agentation, then run npx pi-agentation. It bundles the Agentation Pi skill. Other agents can still consume the same queue through the CLI commands directly.

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.

In the supported setup, annotations are stored on the local Agentation server started by agentation start. If no local server is discovered, Agentation still works in local-only mode and keeps browser state in local storage until you copy or clear it.

Agent Sync is the standard local workflow: the browser toolbar talks to the local Agentation server, and your coding agent consumes that shared state from the same project. Start the stack with npx agentation start; if you are using Pi, the happy path is then npx pi-agentation so Pi can watch the queue and react to new annotations automatically.

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.

Yes. Because Agentation uses the local server as the shared source of truth, annotations can be consumed by multiple users or agents connected to the same workflow. You can also still share the copied markdown output when needed.

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.

Shadow DOM is supported in this fork, so elements inside shadow roots can be identified and annotated. Cross-document iframes are still a hard browser boundary, so Agentation cannot inspect arbitrary iframe contents.

Use agentation start --foreground to see logs directly, or check the log files shown by agentation start --background. You can also run agentation status to verify the stack is running and set AGENTATION_STORE=memory for troubleshooting storage issues.

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