Installation

Choose your setup

• Just want annotations? → Basic Setup below (copy-paste to agent)
• Using Claude Code? → Add the /agentation skill (sets up component + MCP server)
• Building a custom agent? → Run MCP server manually for real-time sync

Most users: Basic Setup. Claude Code users: Use the skill for full auto-setup.

Install the package

npm install agentation -D

Or use yarn, pnpm, or bun.

Add to your app

Add the component anywhere in your React app, ideally at the root level. The NODE_ENV check ensures it only loads in development.

import { Agentation } from "agentation";

function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === "development" && <Agentation />}
    </>
  );
}

Claude Code

If you use Claude Code, you can set up Agentation automatically with the /agentation skill. Install it:

npx skills add benjitaylor/agentation

Then in Claude Code:

/agentation

Detects your framework, installs the package, wires it into your layout, and recommends MCP server setup.

Agent Integration Recommended

Connect Agentation to any AI coding agent that supports MCP. This enables real-time annotation syncing and bidirectional communication.

1. Add the MCP server to your agent

The easiest way to configure Agentation across any supported agent (Claude Code, Cursor, Codex, Windsurf, and more):

npx add-mcp "npx -y agentation-mcp server"

Uses add-mcp to auto-detect your installed agents and write the correct config. Supports 9+ agents.

Or use the interactive wizard for Claude Code specifically:

npx agentation-mcp init

2. Verify setup

Check that everything is configured correctly:

npx agentation-mcp doctor

The server runs on port 4747 by default. Use --port 8080 to change it.

3. Connect the component

Point the React component to your server:

<Agentation
  endpoint="http://localhost:4747"
  onSessionCreated={(sessionId) => {
    console.log("Session started:", sessionId);
  }}
/>

Annotations are stored locally and synced to the server when connected.

• Local-first — Works offline, syncs when server is available
• Session continuity — Rejoins the same session on page refresh
• No duplicates — Only new annotations are uploaded; existing ones are skipped
• Server authority — Agent changes (resolve, dismiss) take precedence on rejoin

This means you can annotate freely, refresh the page, and the agent will see a continuous session rather than fragmented duplicates.

Other agents: Any tool that supports MCP can connect. Use npx add-mcp "npx -y agentation-mcp server" to auto-configure, or manually point your agent's MCP config to the Agentation server. Once connected, the agent will have access to tools like agentation_get_all_pending, agentation_list_sessions, and agentation_resolve.

Requirements

• React 18+ — Uses modern React features
• Client-side only — Requires DOM access
• Desktop only — Not optimized for mobile devices
• Zero dependencies — No runtime deps beyond React

Props

All props are optional. The component works with zero configuration.

Callbacks

Behavior

Agent Sync

See API for full props reference and HTTP endpoints.

Security notes

Agentation runs in your browser and reads DOM content to generate feedback. By default, it does not send data anywhere — everything stays local until you manually copy and paste.

• No external requests — all processing is client-side by default
• Local server only — when using the endpoint prop, data is sent to your local machine only (localhost)
• No data collection — nothing is tracked or stored remotely
• Dev-only — use the NODE_ENV check to exclude from production