Agentation: Annotating Your UI for AI Coding Agents

The Gap Between UI Descriptions and Code References

When a developer asks an AI coding agent to 'fix the spacing around the login button,' the agent must search through the entire codebase hoping to find the right component. Agentation attacks this problem from the browser side. Instead of writing a description, the developer activates the toolbar, clicks the element in question, and copies structured output that includes the CSS selector, screen coordinates, and surrounding context. The agent then has enough information to run a targeted grep rather than a guess. The README states the goal directly: 'instead of describing the blue button in the sidebar, you give the agent .sidebar > button.primary and your feedback.'

How Selector Capture Works

When Agentation is active and you click an element, it identifies the element's class names, CSS selectors, and position on the page. For multi-element work, holding Cmd or Ctrl lets you select elements individually; dragging selects a rectangular region, including empty space. A separate mode pauses CSS animations, Web Animations API transitions, and videos so you can capture a specific frame state before annotating. The structured output it copies to the clipboard is Markdown that combines the selectors, coordinates, and any text notes you added. This output works directly with the clipboard paste interface of Claude Code, Codex, Gemini, Grok, or any other tool that accepts plain text. Agentation also handles shadow roots and same-origin iframes, so embedded components are accessible without any additional configuration.

Installing Agentation and Adding It to a React App

Agentation ships as an npm package and installs as a dev dependency:

npm install agentation -D

Once installed, drop the component into your app's component tree. The README gives this minimal example:

import { Agentation } from 'agentation';

function App() {
  return (
    <>
      <YourApp />
      <Agentation />
    </>
  );
}

The toolbar appears in the bottom-right corner. Clicking it activates annotation mode, and clicking any element after that captures it. The package has zero runtime dependencies beyond the React peer dependencies, which means no additional bundle weight from third-party libraries. React 18 is required; earlier versions are not supported.

Connecting Agentation to an MCP Client

For a tighter integration, Agentation ships a companion package, agentation-mcp, that runs a local HTTP server. You register the server with your MCP client, and feedback flows directly into the agent context without needing to copy and paste. The README shows the server command:

npx -y agentation-mcp server

Once that server is running, tell the toolbar its address:

<Agentation endpoint="http://localhost:4747" />

With this setup, annotations you add in the browser surface inside the agent's context automatically. The repository's monorepo includes both the agentation package and the agentation-mcp package, managed with pnpm workspaces. The MCP package reached version 1.3.0 alongside the main Agentation 3.1.0 release in September 2026.

Scope Boundaries: What Agentation Cannot Do

The README is explicit about platform limits: mobile browsers are not supported. The toolbar is a desktop-only tool. Vue, Svelte, and other non-React frameworks also receive no official support; the package is built for React and assumes React 18 as a peer dependency. Annotations persist within the session but the README does not document a server-side storage layer, so feedback history beyond what you copy to the clipboard requires your own tooling. The PolyForm Shield 1.0.0 license permits personal and internal commercial use but restricts anyone from building a competing product with the code. Teams evaluating Agentation for open-source projects should review the PolyForm Shield terms before adopting it, since it is not an OSI-approved open-source license. The hash routes feature is opt-in and, when enabled, separates annotations and sessions per hash route, which can be useful for single-page applications that use client-side routing. The README also notes a dark/light mode toggle that persists to localStorage, and integration options for capturing identifying attributes and opening detected source locations through an editor integration.

Comparison with Generic Screenshot Annotation Tools

Screenshot annotation tools such as Loom or Marker.io capture a visual image and attach text comments to pixel coordinates. That output is human-readable but not machine-parseable in a way that helps a code search tool. Agentation captures the live DOM instead, producing CSS selectors that map directly to source code. The trade-off is that Agentation requires embedding a React component in your running development server, while screenshot tools work on any URL without code changes. For teams that already have a local dev server running and use AI coding agents regularly, the structured output Agentation produces is more useful than a screenshot with an annotation overlay.

Editorial conclusion

Agentation suits teams that already use AI coding agents such as Claude Code, Codex, or Gemini and want to stop wasting tokens on vague UI descriptions. It is the wrong choice for projects that need Vue or Svelte support, for mobile workflows, or for anyone unwilling to accept PolyForm Shield 1.0.0, which restricts competing commercial use. Before adopting it, verify whether your editor integration supports the source-location feature and whether your MCP client can register the agentation-mcp server at localhost:4747.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes