Agentation Server (CLI)

Overview

Agentation uses a local Go CLI + HTTP server workflow. Start the stack locally, point the toolbar at the HTTP endpoint, and process annotations from your coding agent via project-scoped CLI commands.

toolbar → agentation server → project-scoped CLI loop

Quick Start

1. Start the local stack

# starts both HTTP server + router (single PID)
agentation start

# run in background
agentation start --background

# status / stop
agentation status
agentation stop

2. Configure the toolbar endpoint

<Agentation projectId="my-project" endpoint="http://127.0.0.1:4747" />

In the common local workflow you can omit endpoint and let the toolbar probe the default local server automatically. projectId is still required so the CLI can scope sessions, queues, and watch flows correctly.

3. Discover the project and process annotations

# discover recently active project IDs
agentation projects --json

# inspect one project's sessions + annotation counts
agentation project my-project --json

# fetch pending work for exactly one project
agentation pending my-project --json

# block until new project-scoped work arrives
agentation watch my-project --timeout 300 --json

Load the UI at least once before running projects or watch. The browser registers the projectId with the local server, and that registration is what makes project discovery and project-scoped agent loops work.

4. Act on annotations

# acknowledge that the agent picked the item up
agentation ack <annotation-id>

# reply in the annotation thread
agentation reply <annotation-id> --message "Working on it"

# resolve with an optional summary
agentation resolve <annotation-id> --summary "Updated spacing in Hero.tsx"

# dismiss with a required reason
agentation dismiss <annotation-id> --reason "Out of scope for this change"

Service Configuration

The local server is required for synced sessions, CLI commands, and real-time agent workflows. If you only want local copy/paste output, the browser toolbar can still run without it. The router remains optional and can be disabled by setting its address to 0.

# disable router only
AGENTATION_ROUTER_ADDR=0 agentation start

# custom addresses
agentation start --server-addr 127.0.0.1:4747 --router-addr 127.0.0.1:8787

# require auth for router mutations and /open forwarding
AGENTATION_ROUTER_TOKEN=secret-token agentation start

When AGENTATION_ROUTER_TOKEN is set, mutating router calls such as /register,/unregister, and /open must provide the token.

Lifecycle Isolation

If you run multiple local Agentation stacks on the same machine — for example during integration tests or when working on several repos at once — set an explicit PID file and log paths so each stack has its own lifecycle scope.

AGENTATION_PID_FILE=/tmp/agentation-my-project.pid AGENTATION_LOG_FILE=/tmp/agentation-my-project.stack.log AGENTATION_SERVER_LOG_FILE=/tmp/agentation-my-project.server.log AGENTATION_ROUTER_LOG_FILE=/tmp/agentation-my-project.router.log agentation start --background

HTTP API

The local server exposes endpoints for sessions, annotations, pending work, action requests, and event streams. See the API page for the HTTP surface and public React props.

For the exhaustive CLI package, install, environment-variable, and release reference, see the agentation-cli README.