> ## Documentation Index
> Fetch the complete documentation index at: https://developer.revise.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Comments

> Threads anchored to text, from your UI or your agent.

Comments are threads anchored to ranges of text. They render as chips beside
the page, survive the DOCX round trip, and are readable and writable from the
host.

## Reading threads

```ts theme={null}
const { commentThreads, activeCommentId, commentsOpen } =
  editor.review.getState();
```

Each thread carries its root comment, replies, the anchor it points at, and any
suggestions related to it:

```ts theme={null}
interface ReviseCommentThread {
  root: CommentRecord;
  replies: CommentRecord[];
  anchor: { blockId: string; start: number; end: number } | null;
  relatedSuggestionIds: string[];
}
```

## Writing

Comment bodies are markdown. Every method returns the new comment's ID, or
`null` when the target no longer exists.

```ts theme={null}
// At the user's current selection
editor.review.addCommentAtSelection("Is this cap mutual?");

// At a known range
editor.review.addCommentToRanges(
  [{ blockId: "b12", start: 0, end: 24 }],
  "Confirm the notice period.",
);

// On a whole block, or attached to a suggestion
editor.review.addCommentToBlock("b12", "Needs legal review.");
editor.review.addCommentForSuggestion(suggestionId, "Why this wording?");

// Replies and lifecycle
editor.review.replyToComment(commentId, "Agreed — updated.");
editor.review.setCommentResolved(commentId, true);
editor.review.deleteComment(commentId);
```

Mentions are supported as an optional second argument on each of these.

## Panel and selection

```ts theme={null}
editor.view.setCommentsOpen(true);
editor.review.selectComment(commentId); // scrolls to and highlights the thread
editor.review.selectComment(null);      // clear
```

There is no built-in comments button — chips render inline, and the panel opens
wherever your own UI decides. See [chrome](/editor-sdk/guides/chrome).

One affordance is built in: selecting text in an editable document shows a
small insert-comment chip in the page margin, and clicking it starts a draft on
that selection — the same thing `addCommentAtSelection` does. It stays out of
the way of an in-progress draft, of read-only documents, and of selections that
already carry a thread.

## Comments and suggestions together

A comment can be tied to the suggestions it discusses, which lets a reviewer
resolve the conversation and the edit in one action:

```ts theme={null}
const ids = editor.review.getRelatedSuggestionIds(commentId);
editor.review.acceptCommentSuggestions(commentId); // returns the count
editor.review.rejectCommentSuggestions(commentId);
```

## Agents leaving comments

An agent reviewing a document should usually *comment* rather than rewrite.
The `leave_comment` tool is the agent-facing equivalent of the above:

```ts theme={null}
// Start a thread: one block, exactly one anchor form
await editor.tools.execute("leave_comment", {
  id: "b12",
  anchor: { text: "capped at the fees paid in the preceding twelve months" },
  comment: "Consider making this cap mutual.",
});
```

The other anchor forms are `{ start_text, end_text }` for a range too long to
quote in full, and `{ whole_block: true }` for structural or empty content.

Replying to a thread is the same tool with no anchor:

```ts theme={null}
await editor.tools.execute("leave_comment", {
  reply_to_comment_id: threadId,
  comment: "Agreed — the mutual version is in the market standard.",
});
```

<Warning>
  `leave_comment` anchors to text the agent has actually read. Call a read tool
  such as `read_blocks_from_index` first, or the anchor text will not resolve
  to a range in the loaded context.
</Warning>

Existing threads appear as `<comment-thread>` elements in the HTML read tools
return, so an agent can see what has already been said. A **new** thread that
overlaps an existing unresolved one is rejected: the agent should reply to that
thread instead of repeating the point beside it. When the overlap is deliberate
and the point is genuinely different, list the overlapping IDs in
`acknowledge_existing_thread_ids` to confirm it read them.

## Comment agents

For products where each thread is its own conversation with the model, the
`comments` controller runs an agent scoped to one thread:

```ts theme={null}
await editor.comments.run(threadId, "Draft a redline that addresses this.");
editor.comments.steer(threadId, "Keep it to one sentence.");
editor.comments.cancel(threadId);

useEffect(() => editor.comments.subscribe(setThreadRuns), [editor]);
```

`getState(threadId)` returns that thread's run state, and `subscribe()`
publishes a map of every in-flight run, so a thread list can show per-thread
progress.