# What Comment.io can do

Comment.io is a shared markdown workspace where you and your AI agents write in the same document — editing, commenting, and suggesting changes side by side, with every change attributed to whoever (or whatever) made it.

> **New here?** Start with the comm: use any Comment.io tool, link, or browser access you already have to open it and contribute. If your agent still needs a route, give it [**/llms.txt**](/llms.txt). The capability guide routes supported connectors and skills without relying on the retired CLI or daemon.

## On this page

  - [Use the current comm first](#use-the-current-comm) — pick the smallest access route your agent already has before installing anything

  - [The agent API](#the-agent-api) — for building your own integrations

  - [Identities: which kind of agent to use](#identities-which-kind-of-agent-to-use) — botlets vs. agent handles vs. ephemeral handles, and when to reach for each

  - [Legacy local integration](#the-cli-and-the-daemon) — the CLI, local MCP server, and background daemon are retired

  - [Running your agents in Docker](#running-an-agent-in-docker) — keep your agents' credentials and files sandboxed in a container

  - [Syncing your docs to local files](#syncing-your-docs-to-local-files) — mirror your library as Markdown files on your machine

## Use the current comm first

Start with the comm and task you already have. A skill teaches the workflow, but does not grant tools, identity, or document access.

- **Comment.io tools already available:** use them now. With the standard MCP tools, call `read_comm` with `url_or_slug`; call `create_comm` only when the human explicitly requested a new comm, never to verify setup. Other Comment.io tools follow their own `next_actions`. Hosted connectors accept a slug, token-free document URL, or exact clean CMNT/configured shortlink and consume the latter privately; never pass a raw `?token=` URL.

- **Authenticated HTTPS:** If a clean shortlink hides slug/token, fetch it once with `Accept: text/html, application/json;q=0`, without Authorization or redirects, and accept only an exact token-bearing Comment.io `/d/{slug}` Location. Extract the slug/token. Only for an attributed write—not merely to open, read, or summarize—and absent an anonymity/off-list request: probe the exact same-task, matching-host named registered/Ephemeral identity and reuse it only if `your_role`, `read_only`, and `comments_disabled` allow the action. Before any authenticated GET, classify the supplied credential from its provenance. Keep a creator or personal token unchanged and never add the share-ingress header. Only a credential from a human share URL or invite follows the share path: send the first GET to `/docs/{slug}?docs` with private share Bearer auth and `X-Comment-Share-Ingress: 1`; then switch to returned `your_token`. Then follow its personalized quickstart.

- **URL fetch only (no browser UI/headers):** Use any supplied URL with `mode=agent` and read it directly. For a bare slug or token-free URL, first try `https://comment.io/d/{slug}?mode=agent`. Ask for **Share → Copy for agent** only on `markdown: null` or no readable state. Read-only.

- **Interactive browser:** open the ordinary comm URL and use the visible editor and comments UI.

- **No working route:** fetch [/llms.txt](/llms.txt) once and follow exactly one matching route. Only if it cannot be fetched or has no match, name one missing capability and request one human handoff. Do not claim you entered the comm.

→ **Agent instructions:** [/llms.txt](/llms.txt)
→ **Connected chat app:** [/connect](/connect)

## The agent API

Everything above is built on a plain HTTP API, and you can use it directly. Create docs, read them, edit text, leave comments, and suggest changes — all with `curl` and a bearer token. It's how agents and integrations talk to Comment.io without the CLI.

→ **Full API reference:** [/llms/reference.txt](/llms/reference.txt)
→ **Notifications & @mention contract:** [/llms/notifications.txt](/llms/notifications.txt)

## Identities: which kind of agent to use

This is the part worth understanding well. Comment.io has **three kinds of agent identity**, and they exist for genuinely different jobs.

### Quick comparison

|  | **Ephemeral handle** | **Agent handle** | **Botlet** |
| --- | --- | --- | --- |
| Lives for | One session | Forever | Forever |
| Setup effort | None when the host provides one | One-time, ~1 minute | Create in the browser |
| Eligible for background @mentions | No | Not through the retired local runtime | Not through the retired local runtime |
| Has editable agent instructions | No | Yes | **Yes** |
| Best for | A single coding session | A reusable named assistant | A configured teammate identity |

### Ephemeral handle — a session-scoped local-runtime option

An **ephemeral handle** is a throwaway identity a supported host can mint for one working session. It looks like `@you.e-3f9a2c`. Installing the skill alone only teaches the workflow and does not create an identity or network access.

Use it when you just want your work **attributed and @mentionable** without creating a permanent agent identity. An AI assistant helping you for an afternoon doesn't need a permanent name; its edits can appear under a temporary name instead of a faceless "anonymous," with no permanent profile to maintain.

The trade-offs: it can't answer mentions while you're away, it has no memory between sessions, it expires after about 30 days of inactivity, and it can never be promoted into a botlet. It's deliberately disposable.

→ **Current routes** — a supplied per-doc token identifies only inside that comm. Other supported identity routes are linked from the [startup index](/llms.txt).

### Agent handle — a permanent named assistant

A **registered agent handle** is a permanent identity: a real `@handle` (like `@you.researcher`) with a long-lived secret. Unlike an ephemeral handle, it persists across every doc and every session, so its work is always attributed to the same name. It can be invited to docs by handle, manage a profile, and bookmark starred docs.

Reach for this when you have an assistant you'll use **again and again** and want its contributions to accumulate under one recognizable identity — a "research assistant" or a "release notes writer" you call on across many documents over weeks.

On its own, an agent handle is just an identity. The retired CLI and daemon no longer provide background execution; product-native Claude and Codex plugins are still in progress.

→ **Set it up:** create an agent handle at [**/setup/handle**](/setup/handle), or self-register from a headless host with a key from [**/settings/connections**](/settings/connections). Details are in the [registration reference](/llms/registration.txt).

### Botlet — a standing teammate

A **botlet** is a standing agent with a persistent identity and explicit agent instructions. Creating one in the browser creates that identity and configuration; it does not start an execution runtime.

The retired CLI and daemon no longer run Botlets locally or deliver automatic @mentions. Product-native Claude and Codex plugin support is still in progress.

You shape *how it behaves* by editing its agent instructions in plain language. An ephemeral handle can never become a botlet — botlets are their own thing from the start.

→ **Set it up:** create and configure the identity in the browser. Do not promise background execution until a supported product-native runtime is available.

### Still unsure? Rule of thumb

- **Just want to work on one supplied comm?** → use the tools, HTTPS token, read-only URL-fetch envelope, or browser path already available; no permanent identity is required.

- **A named assistant you'll reuse, that you trigger yourself?** → agent handle.

- **A standing agent that works while you're away after its persistent receive path is verified?** → botlet.

## Legacy local integration

The Comment.io CLI, local MCP server, and background daemon are retired and no longer supported.

Product-native Claude and Codex plugins are still in progress. For now, use Comment.io tools, an authenticated comm URL, read-only URL fetch, the browser, or a hosted connector when available.

→ **Retirement notice:** [/cli-daemon-retired](/cli-daemon-retired)
→ **Current startup index:** [/llms.txt](/llms.txt)

## Running an agent in Docker

The legacy Comment.io Docker runtime was part of the retired CLI and daemon distribution and is no longer supported.

Product-native Claude and Codex plugins are still in progress. Use the browser, authenticated API, or a hosted connector for current work.

→ **Retirement notice:** [/cli-daemon-retired](/cli-daemon-retired)

## Syncing your docs to local files

The CLI-backed local library mirror is retired with the Comment.io daemon. New local sync setup is not supported.

Use the browser, authenticated API, hosted connector search when available, or exported files for current workflows.

→ **Retirement notice:** [/llms/local-sync.txt](/llms/local-sync.txt)

Copies a short pointer to the live agent instructions