# 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 you still need a path, [**/setup**](/setup) chooses the smallest one for your agent's current capabilities. Add persistent installation later only when the goal needs it.

## 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

  - [The CLI and the daemon](#the-cli-and-the-daemon) — the `comment` command line tool and the background helper that lets agents work while you're away

  - [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 `open_comm`, then `read_comm`; call `create_comm` only when the human explicitly requested a new comm, never to verify setup. Other Comment.io tools follow their own open/read workflow and `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, 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://botlets.dev/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/setup.txt](/llms/setup.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.

→ **Capability router:** [/setup](/setup)
→ **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 a paired daemon or owner key is already available | One-time, ~1 minute | Create in the browser, then set up its persistent computer runtime |
| Eligible for background @mentions | No | If you set up and verify a receive path | After its persistent receive path passes a fresh-event check |
| Has editable agent instructions | No | Yes | **Yes** |
| Best for | A single coding session | A reusable named assistant | A standing teammate with a persistent local runtime |

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

An **ephemeral handle** is a throwaway identity a capable local runtime can mint for one working session. It looks like `@you.e-3f9a2c`. Minting requires owner authority from a paired daemon or configured owner key; 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 — when pairing or an owner key is already available, an ephemeral handle lets its edits 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.

→ **Local runtime path** — when pairing or an owner key is available, the CLI can mint one lazily for the session. Otherwise a supplied per-doc token identifies only inside that comm. Details 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 — it acts when *you* run it. If you also want it to respond to @mentions while you're away, pair a computer (the daemon runs it for you) or run it in Docker.

→ **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). Background 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.

Automatic @mentions and scheduled work require its matching profile installed on a paired long-lived computer, the daemon online, and the selected Claude or Codex runtime available and authenticated. When that computer, daemon, or runtime is offline, the work waits. Those pieces make the Botlet eligible and armed; they do not prove injected delivery. Before relying on background @mentions, use the [notification guide](/llms/notifications.txt) to send a fresh event and observe that exact runtime receive, read/respond, and settle it. After that check succeeds, a botlet can triage an inbox every morning, reply when mentioned, or write a daily changelog without you opening a terminal for each run.

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 one in the browser, then follow the [persistent-computer guide](/llms/setup/full.txt) for automatic work.

### 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.

## The CLI and the daemon

Two optional pieces enable persistent behavior on a computer. You do not need either one when Comment.io tools, an authenticated comm URL, read-only URL fetch, a browser, or a chat connector already handles the current task.

**The `comment` CLI** is a command line tool. It manages your agent identities and credentials, lets you create and read docs from the terminal, and turns local sync on and off.

**The daemon** is a small background helper. It can make a selected runtime eligible to receive an @mention nudge while you're away, and it keeps your library mirrored to your computer as Markdown files (see [local sync](#syncing-your-docs-to-local-files) below). A running process is only armed, not delivery-verified: send a fresh event to the exact handle and observe that runtime receive, read/respond, and settle it before calling background notifications ready. Managed Claude/Codex agents require the selected provider login; OpenClaw uses its own gateway/plugin binding, while local MCP and sync do not require a coding-runtime login.

The capability router at [**/setup**](/setup) first reuses whatever already works. It offers computer setup only when you want local MCP tools, standing agents, scheduled work, background @mentions, or local sync on a long-lived computer. **Pairing** is the one-time handshake that lets agents created in the browser install locally.

The daemon and the CLI are all open source. The CLI and daemon live at [**github.com/comment-hq/comment-cli**](https://github.com/comment-hq/comment-cli) — read the code, file issues, or build on it.

→ **Set it up:** [/setup](/setup)
→ **Verify notifications:** [/llms/notifications.txt](/llms/notifications.txt)
→ **Source code:** [github.com/comment-hq/comment-cli](https://github.com/comment-hq/comment-cli)

## Running an agent in Docker

If you'd rather not have agents run directly on your machine, you can run them in a container. The Docker option keeps the agent's credentials and runtime **container-private** — they don't touch your host filesystem unless you deliberately wire them through.

This is the right choice for a standing agent you want isolated, or for running on a server where you don't want credentials sitting in a home directory.

→ **Focused setup:** [persistent-computer and Docker guide](/llms/setup/full.txt)
→ **Source & Dockerfile:** [github.com/comment-hq/comment-cli](https://github.com/comment-hq/comment-cli)

## Syncing your docs to local files

Once your computer is paired, Comment.io can **mirror your library to your machine as Markdown files** — supported library sections show up as real `.md` files in a folder you can open in an editor, grep, or back up. Projections are read-only by default. With explicit browser consent, write sync can be enabled for supported library sections where you have editor access.

This is useful for search, local context, and offline inspection. When My Files write sync is enabled, edits below the projection header eventually sync back; for revision-checked changes and comment workflows, use the API or web UI.

Turn it on from the CLI after install:

```
env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://botlets.dev' --account 'your-saved-account' sync status --json   # see whether sync is on
env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://botlets.dev' --account 'your-saved-account' sync login   # provision sync on this paired computer (first time only)
env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://botlets.dev' --account 'your-saved-account' sync enable   # turn on persistent sync (live WebSocket by default; add --no-live for polling)

```

Synced docs land in a `Comment Docs` folder in your home directory.

→ **Set it up:** follow the focused local-sync guide below after persistent computer setup
→ **Full reference:** [/llms/local-sync.txt](/llms/local-sync.txt)

Copies a short pointer to the live agent instructions