API

Public React props, local HTTP API, and CLI integration surface

Overview

Agentation exposes a small public React API for the browser toolbar and a local CLI/server API for project-scoped agent automation. The browser component is what you ship in your app; the local CLI/server is what powers synced sessions, pending queues, watch loops, and editor routing.

This page covers the public component props and the core CLI/server surface. For the exhaustive npm package, install, environment-variable, and release reference, see the agentation-cli README.

Mount the browser toolbar with a required projectId
Use CLI commands such as pending, watch, reply, and resolve
Use the local HTTP API directly if you need custom tooling around sessions or annotations

Props

<Agentation /> is a thin public wrapper around the CSS toolbar component. These are the current public props exported by @alexgorbatchev/agentation.

Required

projectIdstring

Required project scope used by the local CLI/server for session reuse, pending queues, and watch flows.

Demo mode

demoAnnotationsDemoAnnotation[]

Optional scripted demo annotations rendered when demo mode is enabled.

demoDelaynumberdefault: 1000

Delay in milliseconds between demo annotation steps.

enableDemoModebooleandefault: false

Enable the built-in demo flow instead of normal live annotation capture.

Callbacks

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 or server-backed fields are updated.

onAnnotationsClear(annotations: Annotation[]) => void

Called when all local annotations are cleared.

onCopy(markdown: string) => void

Receives generated markdown when the copy action runs.

onSubmit(output: string, annotations: Annotation[]) => void

Receives the rendered output plus annotations when the send action runs.

onSessionCreated(sessionId: string) => void

Called when a new server-backed session is created.

Sync and delivery

endpointstring

Optional server URL. If omitted, Agentation probes http://127.0.0.1:4747 once and otherwise stays local-only.

sessionIdstring

Join a pre-existing session instead of creating or reusing a project-scoped one.

webhookUrlstring

Default webhook target. Auto-send is controlled by toolbar settings, and the manual send action can still target this URL.

Behavior and UI

copyToClipboardbooleandefault: true

Disable clipboard writes if you want to handle copied output yourself via onCopy.

classNamestring

Custom class applied to the toolbar container for z-index or positioning adjustments.

Component-source navigation

componentEditor"cursor" | "neovim" | "vscode" | "vscode-insiders" | "webstorm"default: "vscode"

Editor protocol used when opening detected source files from the component menu.

getComponentEditorUrl(params: ComponentSourceUrlParams) => string

Override editor URL generation entirely.

navigateToUrl(url: string) => voiddefault: window.location.assign

Override the final navigation side effect when a component source link is opened.

neovimBridgeUrlstringdefault: http://127.0.0.1:8777

Base URL for the Neovim router when componentEditor="neovim".

neovimProjectIdstring

Optional project ID passed to the Neovim router for session resolution.

copyComponentSourcePathbooleandefault: true

Copy the resolved source path to the clipboard when opening a component source link.

Basic usage

Receive annotation data directly in your code:

import { Agentation, type Annotation } from "@alexgorbatchev/agentation";

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

  return (
    <>
      <YourApp />
      <Agentation projectId="my-project" onAnnotationAdd={handleAnnotation} />
    </>
  );
}

Annotation type

The Annotation object passed to callbacks. See Agentation Format for the wire schema and server-backed fields.

type Annotation = {
  // Core fields
  id: string;
  x: number;
  y: number;
  comment: string;
  element: string;
  elementPath: string;
  timestamp: number;

  // Element context
  selectedText?: string;
  boundingBox?: { x: number; y: number; width: number; height: number };
  nearbyText?: string;
  cssClasses?: string;
  nearbyElements?: string;
  computedStyles?: string;
  fullPath?: string;
  accessibility?: string;
  isMultiSelect?: boolean;
  isFixed?: boolean;
  reactComponents?: string;
  sourceFile?: string;
  elementBoundingBoxes?: Array<{ x: number; y: number; width: number; height: number }>;

  // Server-backed metadata
  sessionId?: string;
  url?: string;
  intent?: "fix" | "change" | "question" | "approve";
  severity?: "blocking" | "important" | "suggestion";
  status?: "pending" | "acknowledged" | "resolved" | "dismissed";
  thread?: ThreadMessage[];
  createdAt?: number;
  updatedAt?: number;
  resolvedAt?: number;
  resolvedBy?: "human" | "agent";
  authorId?: string;

  // Local-only sync tracking
  _syncedTo?: string;
  _reviewedAt?: number;
};

type ThreadMessage = {
  id: string;
  role: "human" | "agent";
  content: string;
  timestamp: number;
};

CLI command surface

The supported automation path is the project-scoped CLI. Add --json when you want machine-readable output.

# lifecycle
agentation start
agentation status
agentation stop

# project discovery + queue inspection
agentation projects --json
agentation project my-project --json
agentation pending my-project --json
agentation watch my-project --timeout 300 --json

# annotation actions
agentation ack <annotation-id>
agentation reply <annotation-id> --message "Working on it"
agentation resolve <annotation-id> --summary "Updated spacing in Hero.tsx"
agentation dismiss <annotation-id> --reason "Out of scope for this change"

HTTP API

The local Agentation server (started with agentation start) provides a REST API for programmatic access. For agent automation, prefer project-scoped CLI commands or include ?projectId=... on the corresponding HTTP requests.

Sessions

POST	/sessions	Create a new session
GET	/sessions	List sessions (optionally filter with `?projectId=...`)
GET	/sessions/:id	Get session with annotations
POST	/sessions/:id/action	Request agent action for a session

Annotations

POST	/sessions/:id/annotations	Add annotation
GET	/annotations/:id	Get annotation
PATCH	/annotations/:id	Update annotation status or metadata
DELETE	/annotations/:id	Delete annotation
POST	/annotations/:id/thread	Add thread message
GET	/sessions/:id/pending	Get pending annotations for one session
GET	/pending	Get pending annotations across all projects, or filter with `?projectId=...`

Events (SSE)

GET	/sessions/:id/events	Session event stream (optionally add `?agent=true`)
GET	/events	Global event stream (supports `?projectId=...`, `?domain=...`, and `?agent=true`)

Health

GET	/health	Health check
GET	/status	Server status

POST /sessions/:id/action accepts a JSON body shaped like { "output": "..." }and emits an action.requested event containing the session, current annotations, and request timestamp.

Real-Time Events

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

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

# Project-scoped: events across all sessions for one project
curl -N "http://127.0.0.1:4747/events?projectId=my-project"

# Agent watch flow: only the stream shape used by CLI watch
curl -N "http://127.0.0.1:4747/events?agent=true&projectId=my-project"

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

Event types

annotation.created — New annotation added
annotation.updated — Annotation modified (comment, status, 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

Variable	Description	Default
AGENTATION_BASE_URL	Default base URL for CLI data commands such as `pending`, `watch`, `reply`, and `resolve`	http://localhost:4747
AGENTATION_STORE	Storage backend (`sqlite` or `memory`)	sqlite
AGENTATION_DB_PATH	Override the SQLite file path completely	derived from XDG_DATA_HOME
XDG_DATA_HOME	Base directory used to derive the default SQLite location	~/.local/share
AGENTATION_SERVER_ADDR	Default address for `agentation start`; set to `0` to disable the HTTP server	127.0.0.1:4747
AGENTATION_ROUTER_ADDR	Default address for the optional router; set to `0` to disable it	127.0.0.1:8787
AGENTATION_PID_FILE	Override the single PID file used for stack lifecycle isolation	platform-specific runtime path
AGENTATION_LOG_FILE	Override the stack supervisor log file for background mode	derived runtime path
AGENTATION_SERVER_LOG_FILE	Override the server log file	derived runtime path
AGENTATION_ROUTER_LOG_FILE	Override the router log file	derived runtime path
AGENTATION_ROUTER_TOKEN	Optional auth token for router mutation endpoints such as `/register`, `/unregister`, and `/open`	unset

Lower-level router tuning variables and npm install fallback variables are documented in the CLI README.

Storage

By default, data is persisted to SQLite at $XDG_DATA_HOME/agentation/store.db if XDG_DATA_HOME is set, otherwise ~/.local/share/agentation/store.db. To use in-memory storage:

AGENTATION_STORE=memory agentation start --foreground

Programmatic Usage

# Start local stack (server + router)
agentation start

# Disable the router for a server-only workflow
AGENTATION_ROUTER_ADDR=0 agentation start

# Target a non-default API endpoint
AGENTATION_BASE_URL=http://127.0.0.1:5757 agentation pending my-project --json

# Watch + reply from a custom agent loop
AGENTATION_BASE_URL=http://127.0.0.1:5757 agentation watch my-project --json
AGENTATION_BASE_URL=http://127.0.0.1:5757 agentation reply <annotation-id> --message "On it"

See Agentation Server (CLI) for the guided local workflow and lifecycle notes.