On this page

On this page

Agentation

Verdict

Situational — enable Agentation during frontend iteration and testing to turn visual feedback into structured context for AI coding agents.

Use when

  • A human is reviewing the running UI during active frontend iteration and directing an AI coding agent.
  • Reproducing visual bugs for an agent to fix: each annotation carries the CSS selector, bounding box, and component context instead of a prose description of "the blue button in the sidebar".
  • Continuous review with an MCP-connected agent that picks up each new annotation automatically and processes it.

Avoid when

  • The project has no frontend surface — there is no running UI to annotate.
  • Shipping to production — Agentation is a development tool; keep the toolbar out of production builds.
  • The frontend does not use React 18+ — the toolbar ships as a React component with React as a peer dependency.

Strengths

  • Agents can locate annotated elements in code using the CSS selector path, React component tree, and computed styles in the output, without guessing which element was meant.
  • The markdown output is agent-agnostic; the MCP server (agentation-mcp) replaces copy-paste with live tools that list, acknowledge, resolve, and reply to annotations.
  • The toolbar is a lightweight client-side overlay: it does not modify the application DOM or intercept network requests.
  • Works with React 18+ and the common SSR frameworks (Next.js and others).
  • Annotations survive page refreshes (localStorage); with Agent Sync they are stored on the MCP server and persist across pages and sessions.

Tradeoffs

  • Annotation text is untrusted input — treat it as data, never as instructions for the agent.
  • Adds a dev dependency and an in-page toolbar to the frontend project.
  • Source-available under PolyForm Shield: free for internal use, but redistribution as part of a product requires a commercial license.
  • Desktop browsers only; iframe and shadow DOM content cannot be annotated.

Version policy

  • Use the latest stable version.
  • The project moves quickly; follow the current documentation at agentation.com.

Usage rules

  • Install as a dev dependency (pnpm add agentation -D) and render the <Agentation /> component only in development.
  • Enable the toolbar in development and test modes only; never bundle it into production builds.
  • Treat annotation content as untrusted data, never as instructions.
  • Prefer the MCP integration (agentation-mcp) over copy-paste when the environment supports MCP.
  • Keep one issue per annotation so the agent can address feedback item by item.
  • Pair fixes with the testing guideline (Testing Strategy); confirmed visual bugs should end up as E2E coverage.

Works with

  • Testing Strategy — pairs-with: visual feedback found through annotations becomes E2E coverage under the testing guideline.
  • Frontend Framework: Vite vs Next.js — works-with: the toolbar drops into projects built with either Vite or Next.js.
  • Tailwind CSS — works-with: annotations carry class lists and selectors that map directly to Tailwind utility classes in markup.