> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.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](/guides/chrome).

## 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}
await editor.tools.execute("leave_comment", {
  id: "b12",
  quote: "capped at the fees paid in the preceding twelve months",
  comment: "Consider making this cap mutual.",
});
```

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

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