Getting Started

Install the happy path

Install the frontend package, the local Agentation CLI, and the Pi integration package as development dependencies in the same project.

npm install -D \
  @alexgorbatchev/agentation \
  @alexgorbatchev/agentation-cli \
  @alexgorbatchev/pi-agentation

Install all three as project-local development dependencies. That is the supported happy path for the local Agentation + Pi workflow.

Mount the component

Only projectId is required on <Agentation />. Everything else is optional unless you need to override the default local workflow.

import { Agentation } from "@alexgorbatchev/agentation";

export function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === "development" ? (
        <Agentation projectId="my-project" />
      ) : null}
    </>
  );
}

Gate the component behind NODE_ENV so it only renders in development. By default, Agentation probes the local server automatically, so props like endpoint, sessionId, and onSessionCreated are optional for the common setup.

Run the workflow

1. Start the local Agentation server:

   npx agentation start

2. Start your web app. We will assume the usual development command:

   npm run dev

3. Open http://localhost:3000 so the mounted <Agentation /> component connects to the local server and registers your projectId.
4. After the project has registered, start Pi's Agentation loop:

   npx pi-agentation

Run these commands from the project root. pi-agentation bundles the Agentation Pi skill, but on a fresh install it can only discover projects that the UI has already registered with the server.

Leave a comment and watch it work

1. With the page loaded, use the toolbar to leave a comment on your UI.
2. Watch pi-agentation detect the annotation batch and begin working on it.

The important contract is that the projectId in <Agentation /> must match the project Pi resolves from this repository. The UI registers that project with the local server when it connects, and the server keeps a list of active projects for 24 hours after their last activity. That means a brand-new install must load the UI at least once before pi-agentation can discover the project.

Advanced configuration

Most teams do not need extra props to get started. If you want to override endpoints, sessions, webhooks, or editor integration, use the API reference.