/ docs / agent-handoff

# Hand off feedback to your AI agent.

Review feedback in the dashboard, mark items Ready for Agent, copy a prompt, and let Claude Code or Codex work the queue.

## CRRT developer resources

The CRRT Agent API is an authenticated HTTP API for working on shared feedback. Download the [OpenAPI 3.1 specification](/openapi.json) for endpoint descriptions, request parameters, response schemas, and authentication. Start with the [CRRT agent guide](/llms.txt) for when-to-use guidance. No official CLI or MCP server is currently published; use an HTTP client such as curl.

Get a scoped share token from a human-created agent handoff. Announce presence before reading state. Work only on accepted comments, claim each item before editing, and report progress through the operations endpoint. Humans review the resulting changes. A missing or invalid token returns 401; an expired or revoked share returns 410. Keep tokens in environment variables and send them in the Authorization header.

bash

```
curl --fail-with-body -X POST \
  "https://crrt.ai/api/v1/agent/shares/$CRRT_SHARE_SLUG/presence" \
  -H "Authorization: Bearer $CRRT_SHARE_TOKEN" \
  -H "X-Agent-Id: my-agent" \
  -H "Content-Type: application/json" \
  --data '{"status":"reading","summary":"Reviewing accepted feedback"}'

curl --fail-with-body \
  "https://crrt.ai/api/v1/agent/shares/$CRRT_SHARE_SLUG/state" \
  -H "Authorization: Bearer $CRRT_SHARE_TOKEN"
```

## The loop

1.  Your customer drops a CRRT on your app via the widget. The comment lands in the dashboard with **Open** status.
2.  You triage it — accept, reject, or leave open. Accepted items move to **Ready for Agent**.
3.  Open the **Agent handoff** sidebar. The hero shows your count of ready items and a single CTA: `Send N crrts to <agent>`.
4.  Click **Send**. The dashboard generates a scoped prompt and copies it to your clipboard. Pick the agent (Claude Code, Codex, generic) from the caret on the right.
5.  Paste the prompt in your agent. It reads only the Ready items via a per-share bearer token, claims them, fixes them, and marks them **Ready for testing**.
6.  Test the proposed change, then mark it **Done**. The agent never makes that final call.
7.  The sidebar reflects the queue live — claimed, working, ready for testing, done — as the work moves forward.

## Supported agents

The dashboard generates the prompt for each target. The agent doesn't need a special integration — it just needs to read the share token URL we put in the prompt and call the agent API.

*   **Claude Code** — paste in the chat. The prompt embeds the share URL and tells Claude Code which tools to use to fetch, claim, and update comments.
*   **Codex** — paste in the prompt area. Same shape, different formatting.
*   **Generic** — for Cursor, Windsurf, Cline, or any tool that accepts a free-form prompt. Same data, less tool-specific syntax.

## Under the hood

The handoff is mediated by a **feedback share**: a per-handoff record that bundles a set of comments, a scope (page, selection, or whole project), an expiry, and a one-time bearer token. The agent only ever sees the comments inside the share — nothing else from the project.

### 1\. Create a share

http

```
POST /api/v1/feedback-shares
Authorization: Bearer <REVIEWER_API_TOKEN>
Content-Type: application/json

{
  "projectId": "proj_acme_marketing",
  "scopeType": "selection",
  "commentIds": ["..."]
}

→ 201 Created
{
  "shareId": "...",
  "slug": "...",
  "token": "...",
  "tokenUrl": "https://crrt.ai/api/v1/agent/shares/.../state?token=..."
}
```

The dashboard does this for you automatically when you click **Send**. You can also call the endpoint directly if you're scripting your own workflow.

### 2\. Generate the prompt

http

```
GET /api/v1/feedback-shares/<shareId>/prompt?target=claude-code
Authorization: Bearer <REVIEWER_API_TOKEN>

→ 200 OK
{
  "prompt": "You are reviewing the Ready-for-Agent items at <tokenUrl>...\n…",
  "tokenUrl": "..."
}
```

Choose `target=claude-code`, `codex`, or `generic`. The returned prompt embeds the share URL plus instructions tailored to that agent.

### 3\. Agent reads the share

http

```
GET /api/v1/agent/shares/<slug>/state
Authorization: Bearer <share-token>

→ 200 OK
{
  "share": { "id": "...", "scopeType": "selection", ... },
  "project": { "publicKey": "...", "name": "...", ... },
  "comments": [
    {
      "id": "...",
      "body": "El contraste del CTA contra el fondo no pasa AA.",
      "selector": "button.cta-primary",
      "pageUrl": "https://acme.test/pricing",
      "reviewStatus": "accepted",
      "implementationStatus": "unassigned"
    }
  ],
  "presence": [],
  "capabilities": { "presence": true, "ops": true }
}
```

The agent fetches the state, claims comments (`POST .../presence`, `POST .../ops`), reports progress, and marks each item Ready for testing when it opens a pull request. The dashboard polls and renders the same state live; a human marks the item Done after reviewing the result.

The bearer token in the share URL is scoped to that share only. Revoke a share and the agent immediately loses access — useful if you ever need to stop a job mid-flight.

## Custom integrations

If you're building your own agent or a different review tool, integrate against the agent API directly. The endpoints are documented in the `README` under `/api/v1/agent/...`. Anything that can speak HTTP and respect a bearer token can participate in the loop.

[next: run your own CRRT instance →](/docs/self-host)