Installation

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 renders the toolbar only in development.

import { Agentation } from "agentation";


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

Connect your agent

Claude Code, Codex, Gemini CLI, Grok Build, and other clients can connect through MCP. Use Node.js 24 LTS for a new setup. Node.js 22 LTS and 20 are also compatible.

1. Register the MCP server

claude mcp add agentation -- npx -y agentation-mcp server

Restart your agent or reload its MCP servers after configuration. Your agent starts the server when it connects.

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" />

Annotations are stored locally and synced to the server when connected. Registering the server with your agent does not set this endpoint for you. Add a note in the browser, then ask your agent to list pending feedback to check the complete connection.

• 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

Customize your setup

The API reference covers every prop and callback, including Copy formats, source editor links, hash routing, and integrations with dialogs and menus.