Agentation.dev - AI Agent Feedback and Annotation Tool

Overview

Agentation is a developer tool that enables precise feedback for AI coding agents by allowing developers to annotate DOM elements on live webpages and generate structured markdown output. The name combines “agent” and “annotation,” reflecting its core purpose: bridging the gap between human developers and AI coding assistants by providing agents with exact technical details about visual elements.

Key Insight: Agents can find and fix code much faster when given precise technical context (CSS selectors, class names, bounding boxes) rather than vague descriptions of what needs to change.

Problem Statement

Traditional feedback to AI agents relies on imprecise descriptions:

• ❌ “The blue button in the sidebar needs to be wider”
• ❌ “Fix the spacing in the navigation”
• ❌ “The font looks wrong”

These descriptions require agents to search the codebase for matching elements, wasting tokens and increasing latency. Agentation solves this by capturing:

• ✅ Exact CSS selectors
• ✅ Element identifiers (class names, IDs, alt text)
• ✅ Bounding box positions
• ✅ Computed CSS styles
• ✅ Contextual surrounding text

Core Features

Annotation Methods

Element Clicking

• Click any DOM element to capture it
• Intelligent identification by:
  • Text content
  • Alt attributes
  • Class names
  • Semantic HTML structure
  • Nearby identifying text

Multi-Select

• Drag to select multiple elements simultaneously
• Apply same feedback to bulk elements
• Perfect for repeated styling changes

Area Selection

• Select empty space to provide layout feedback
• Annotate gaps, spacing, or alignment issues
• Useful for whitespace and positioning problems

Text Selection

• Highlight specific text content
• Capture context around selected text
• Precise feedback for copy or content changes

Animation Freezing

• Pause CSS animations to annotate transient states
• Capture state-specific styling issues
• Debug hover, focus, or animated states

Output Formats

Agentation generates four detail levels for different agent complexity needs:

Level	Use Case	Content
Compact	Simple fixes, token-limited agents	Minimal identifiers, basic location
Standard	Balanced workflows	Element location, class names, text content
Detailed	Complex changes	Full context, bounding boxes, nearby elements
Forensic	Layout debugging	Computed CSS, styles, full DOM context

Output Format: Plain Markdown that any AI coding tool can parse

• Developers can edit before pasting (add context, reorder by priority, add instructions)
• Works with Claude Code, Cursor, Windsurf, and other agents
• No proprietary format—fully portable

Markdown Output Example

## Button in Sidebar  
- Element: button.primary-action  
- Location: Top-right area  
- Current text: "Save"  
- BoundingBox: {x: 1200, y: 50, width: 80, height: 40}  
- Class names: ["primary-action", "btn", "rounded"]  
  
Change needed: Increase button width to 120px and add hover effect  

Technical Architecture

Installation and Integration

Setup:

npm install agentation  

React Component Integration:

import { Agentation } from 'agentation';  
  
export default function App() {  
  return (  
    <>  
      <YourApp />  
      <Agentation   
        onCopy={(markdown) => {  
          // Handle markdown output  
        }}  
      />  
    </>  
  );  
}  

Requirements:

• React 18+ (peer dependency)
• TypeScript (full type definitions exported)
• Browser environment with DOM access

Privacy and Performance

Client-Side Only:

• Runs entirely in browser
• No network requests
• No remote data collection
• GDPR/privacy compliant

Data Storage:

• Annotations stored locally in localStorage
• Keyed by page pathname
• Persist across page refreshes
• Auto-clear after 7 days
• No server-side storage

Browser Compatibility:

• Modern browsers with DOM and localStorage support
• Works across different device sizes
• Responsive design annotations

Framework Compatibility

Supported Frameworks:

• Next.js (App & Pages Router)
• Remix
• Astro
• Gatsby
• Vue.js applications
• Any React-based framework

Conditional Rendering:

{process.env.NODE_ENV === 'development' && <Agentation />}  

API and Callbacks

Agentation exposes callbacks for custom integrations:

<Agentation  
  onAnnotationAdd={(annotation) => {  
    // Custom handler when annotation created  
    // Example: Send to database, Slack webhook  
  }}  
  onAnnotationDelete={(id) => {  
    // Handle deletion  
  }}  
  onAnnotationUpdate={(id, data) => {  
    // Handle updates  
  }}  
  onAnnotationsClear={() => {  
    // Handle clear all  
  }}  
  onCopy={(markdown) => {  
    // Handle markdown copy to clipboard  
    // Integration points:  
    // - MCP servers  
    // - Custom agent tools  
    // - Slack notifications  
    // - Database logging  
  }}  
/>  

Integration Examples:

• Save annotations to database for tracking
• Send to Slack channel for team review
• Log to analytics
• Export to MCP servers for agents
• Custom webhook integrations

Use Cases

Frontend Development with AI Agents

Typical Workflow:

1. Developer runs application
2. Sees visual bug or desired change
3. Uses Agentation to annotate the element
4. Copies structured markdown output
5. Pastes into AI agent (Claude Code, Cursor, etc.)
6. Agent locates code via CSS selectors/class names
7. Agent implements fix immediately
8. Developer reviews changes

Documentation Building

Original creator Benji Taylor reported extensive use during complex UI refinement:

• “Using multi-select annotation constantly when building docs”
• Selecting all navigation links needing same hover treatment
• Batch annotation for repeated styling patterns
• Consistent visual feedback across sections

Layout and Spacing Feedback

Area Selection Use:

• Annotate empty space for padding/margin issues
• Provide feedback on whitespace and alignment
• Debug responsive layout problems
• Identify gap and gutter inconsistencies

Interactive State Debugging

Animation Freezing Use:

• Annotate hover states precisely
• Capture focus states
• Debug animation-related issues
• Feedback on transient visual states

Design System Refinement

• Batch annotation of component variants
• Consistent feedback across similar elements
• Style and token identification
• Documentation of spacing and sizing

Key Differentiators

1. Precision Over Description

Agentation captures exact technical context:

• CSS selectors agents can search immediately
• Computed styles for accurate reproduction
• Bounding boxes for spatial feedback
• No ambiguity in element identification

2. Tight Feedback Loops

Philosophy: “The point is each pass counts”

• Each iteration produces actionable output
• Agents can implement changes immediately
• Structured format reduces misunderstanding
• Works across hundreds of iterations efficiently

3. Flexible Output Levels

Different agents need different context:

• Compact for token-limited scenarios
• Detailed for complex layout changes
• Forensic for debugging edge cases
• Developers choose based on agent capability

4. Client-Side Privacy

• No server-side data collection
• Annotations stored locally only
• No third-party access
• Compliant with data privacy regulations

5. Framework Agnostic Output

• Plain Markdown format
• Works with any AI agent
• Portable across tools
• No proprietary dependencies

Workflow Integration

Direct Copy-Paste Flow

1. Annotate: Click elements, add feedback
2. Copy: Generate markdown
3. Paste: Into AI agent chat
4. Implement: Agent makes changes
5. Iterate: Repeat for refinements

Custom Integration Flow

1. Annotate: Click elements
2. Webhook: Send to custom system
3. Database: Store annotations
4. Batch: Process multiple annotations
5. Automation: Custom workflows

Team Collaboration Flow

1. Annotate: Multiple team members
2. Share: Export or store annotations
3. Review: Centralized feedback
4. Track: Manage changes across codebase

Target Users

Primary: Frontend developers and engineers working with AI coding assistants

• Claude Code users
• Cursor users
• Windsurf users
• Any agent-based coding workflow

Secondary:

• Design engineers
• QA engineers providing visual feedback
• Documentation writers
• Design system maintainers

Comparison to Alternatives

vs. Manual Descriptions:

• ✅ Precise technical context vs. vague descriptions
• ✅ Automated capture vs. manual typing
• ✅ Reduces interpretation errors

vs. Screenshot Annotations:

• ✅ Structured data vs. images only
• ✅ Agent-parseable vs. visual-only feedback
• ✅ Actionable selectors vs. pixel positions

vs. Browser DevTools:

• ✅ Optimized for agents vs. developer debugging
• ✅ Markdown export vs. manual copy/paste
• ✅ Multiple selection modes vs. single element inspection

Installation and Setup

Basic Setup

# Install package  
npm install agentation  
  
# Add to your React app  
import { Agentation } from 'agentation';  
  
function App() {  
  return (  
    <>  
      <YourApplication />  
      <Agentation />  
    </>  
  );  
}  

Next.js Setup

// app/layout.jsx or pages/_app.jsx  
import dynamic from 'next/dynamic';  
  
const Agentation = dynamic(  
  () => import('agentation').then(m => m.Agentation),  
  { ssr: false }  
);  
  
export default function RootLayout() {  
  return (  
    <>  
      {process.env.NODE_ENV === 'development' && <Agentation />}  
      {/* Your app */}  
    </>  
  );  
}  

With Custom Handlers

<Agentation  
  onCopy={(markdown) => {  
    // Send to MCP server  
    window.agentAPI?.annotate(markdown);  
      
    // Or log to backend  
    fetch('/api/annotations', {  
      method: 'POST',  
      body: JSON.stringify({ feedback: markdown })  
    });  
  }}  
/>  

Community and Resources

GitHub: Open source repository (TypeScript/React)
npm: Published package with full type definitions
Creator: Benji Taylor (founder/lead developer)

Adoption:

• Used by frontend developers working with AI agents
• Growing adoption in AI-assisted development workflows
• Community-driven open source project

Limitations and Considerations

⚠️ Development Only:

• Typically not deployed to production
• Use conditional rendering based on NODE_ENV

⚠️ Local Storage Limited:

• Annotations persist 7 days only
• Not suitable for long-term annotation storage
• Requires custom backend for persistence

⚠️ Agent Dependency:

• Output quality depends on agent’s ability to parse markdown
• Works best with capable agents (Claude, GPT-4, etc.)
• Simpler agents may not understand complex structure

⚠️ DOM Dependent:

• Only annotates currently rendered DOM
• Client-side rendering required
• May have issues with dynamic content changes

Related Tools and Concepts

• Claude Code - AI coding agent
• Cursor - AI-powered code editor
• Model Context Protocol - Agent integration standard
• AI-Assisted Development - Broader category
• Feedback Loops - Core concept

Key Takeaways

✅ Precision: Exact CSS selectors and technical context
✅ Efficiency: Tight feedback loops with agents
✅ Flexibility: Multiple output detail levels
✅ Privacy: Client-side only, no data collection
✅ Portability: Plain Markdown, framework agnostic

Resources

• Website: https://agentation.dev
• GitHub: Open source repository
• npm: Installable package
• Docs: In-tool documentation and guides

Notes

• Created by Benji Taylor, exploring feedback loops with AI agents
• Recently featured in developer communities focused on AI-assisted coding
• Growing adoption as AI agents become more capable at code modification
• Ideal complement to modern AI coding agents like Claude Code and Cursor