Agentation is currently desktop only.

Overview

Agentation exposes callbacks that let you integrate annotations into your own workflows — send to a backend, pipe to terminal, trigger automations, or build custom AI integrations.

• Sync annotations to a database or backend service
• Build analytics dashboards tracking feedback patterns
• Create custom AI integrations (MCP servers, agent tools)

Props

onAnnotationAdd(annotation: Annotation) => void
Called when an annotation is created

onAnnotationDelete(annotation: Annotation) => void
Called when an annotation is deleted

onAnnotationUpdate(annotation: Annotation) => void
Called when an annotation comment is edited

onAnnotationsClear(annotations: Annotation[]) => void
Called when all annotations are cleared

onCopy(markdown: string) => void
Callback with the markdown output when copy is clicked

onSubmit(output: string, annotations: Annotation[]) => void
Called when "Send Annotations" is clicked

copyToClipboardboolean
default: true
Set to false to prevent writing to clipboard (if handling via onCopy)

endpointstring
MCP server URL for syncing annotations

sessionIdstring
Pre-existing session ID to use

onSessionCreated(sessionId: string) => void
Called when a new session is created

webhookUrlstring
Webhook URL to receive annotation events

Basic usage

Receive annotation data directly in your code:

import { Agentation, Annotation } from "agentation";

function App() {
  const handleAnnotation = (annotation: Annotation) => {
    console.log(annotation.element, annotation.comment);
  };

return (
    <>
      <YourApp />
      <Agentation onAnnotationAdd={handleAnnotation} />
    </>
  );
}

Annotation type

The Annotation object passed to callbacks. See Agentation Format for the full schema.

type Annotation = {
  // Required
  id: string;              // Unique identifier
  comment: string;         // User's annotation text
  elementPath: string;     // CSS selector path
  timestamp: number;       // Unix timestamp (ms)
  x: number;               // % of viewport width (0-100)
  y: number;               // px from document top
  element: string;         // Tag name ("button", "div")

// Recommended
  url?: string;            // Page URL
  boundingBox?: {          // Element dimensions
    x: number;
    y: number;
    width: number;
    height: number;
  };

// Context (varies by output format)
  reactComponents?: string;   // Component tree
  cssClasses?: string;
  computedStyles?: string;
  accessibility?: string;
  nearbyText?: string;
  selectedText?: string;      // If text was selected

// Browser component fields
  isFixed?: boolean;       // Fixed-position element
  isMultiSelect?: boolean; // Created via drag selection

// Annotation kind (defaults to "feedback")
  kind?: "feedback" | "placement" | "rearrange";

// Layout mode data
  placement?: {
    componentType: string;
    width: number;
    height: number;
    scrollY: number;
    text?: string;
  };
  rearrange?: {
    selector: string;
    label: string;
    tagName: string;
    originalRect: { x: number; y: number; width: number; height: number };
    currentRect: { x: number; y: number; width: number; height: number };
  };
};

HTTP API

The agentation-mcp server provides a REST API for programmatic access:

Sessions

Annotations

Events (SSE)

Health

Real-Time Events

Subscribe to real-time events via Server-Sent Events:

# Session-level: events for a single page
curl -N http://localhost:4747/sessions/:id/events

# Global: events across ALL sessions
curl -N http://localhost:4747/events

# Filtered by domain: events for pages on a specific domain
curl -N "http://localhost:4747/events?domain=localhost:3001"

# Reconnect after disconnect (replay missed events)
curl -N -H "Last-Event-ID: 42" http://localhost:4747/sessions/:id/events

Event types

• annotation.created — New annotation added (includes kind field for design annotations)
• annotation.updated — Annotation modified (comment, status, design data, etc.)
• annotation.deleted — Annotation removed
• session.created — New session started
• session.updated — Session updated
• session.closed — Session closed
• action.requested — Agent action requested
• thread.message — New message in annotation thread

Environment Variables

Storage

By default, data is persisted to SQLite at ~/.agentation/store.db. To use in-memory storage:

AGENTATION_STORE=memory npx agentation-mcp server

Programmatic Usage

import { startHttpServer, startMcpServer } from 'agentation-mcp';

// Start HTTP server on port 4747
startHttpServer(4747);

// Start MCP server (connects via stdio)
await startMcpServer('http://localhost:4747');

See MCP Server for AI agent integration and available tools.