Agentation is currently desktop only.

## 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](https://modelcontextprotocol.io/). 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](https://github.com/neondatabase/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

|     |     |
| --- | --- |
| `onAnnotationAdd` | Fired when an annotation is added |
| `onAnnotationDelete` | Fired when an annotation is deleted |
| `onAnnotationUpdate` | Fired when an annotation comment is edited |
| `onAnnotationsClear` | Fired when all annotations are cleared |
| `onCopy` | Fired when copy button is clicked (receives markdown) |
| `onSubmit` | Fired when "Send Annotations" is clicked |

### Behavior

|     |     |
| --- | --- |
| `copyToClipboard` | Auto-copy on add (default: `true`) |
| `className` | Custom class for positioning or z-index adjustments |

### Agent Sync

|     |     |
| --- | --- |
| `endpoint` | Server URL (e.g., "http://localhost:4747") |
| `sessionId` | Join an existing session (optional) |
| `onSessionCreated` | Fired when new session is created (receives `sessionId: string`) |

See [API](/content/api/index.html) 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.