> ## Documentation Index
> Fetch the complete documentation index at: https://revise.io/developer/docs/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 and are preserved in DOCX import and export. Your code can read and
write them.

## Read threads

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

Each thread has a root comment, replies, an anchor, and related suggestions:

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

## Add comments

Comment bodies are Markdown. Each 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);
```

Each method takes optional mentions as an additional argument.

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

The SDK has no comments button. Chips render inline, and your UI opens the
panel. See [chrome](/developer/docs/developer/docs/editor-sdk/guides/chrome).

Selecting text in an editable document shows an insert-comment chip in the
page margin. Clicking it starts a draft on the selection, like
`addCommentAtSelection`. The chip is hidden during a draft, in read-only
documents, and on selections that already have a thread.

## Comments and suggestions together

A comment can be linked to suggestions. A reviewer can then accept or reject
those suggestions from the comment:

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

## Agent comments

The `leave_comment` tool adds comments from an agent:

```ts theme={null}
// Start a thread on one block with 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.",
});
```

Other anchor forms are `{ start_text, end_text }` for a long range, and
`{ whole_block: true }` for structural or empty content.

To reply, call the same tool without an anchor:

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

<Warning>
  `leave_comment` anchors only to text the agent has read. Call a read tool
  such as `read_blocks_from_index` first, or the anchor does not resolve.
</Warning>

If the anchor text is not in the block you named, but exactly one block you
have read contains it, the comment goes there instead. The result reports both:
`data.blockId` is where it landed and `data.requestedBlockId` is the block you
asked for. Block IDs change when a file is imported again, so this keeps a
stale ID from failing.

Read tools return existing threads as `<comment-thread>` elements in their
HTML. A new thread that overlaps an unresolved thread is rejected, and the
agent should reply to that thread instead. To add an overlapping thread
anyway, list the overlapping IDs in `acknowledge_existing_thread_ids`.

Tool comments are signed "Revise Agent" unless you set
[`agent.name`](/developer/docs/developer/docs/editor-sdk/guides/tracked-changes#attribution).

## Comment agents

The `comments` controller runs an agent scoped to one thread. Use it when each
thread is a separate conversation with the model:

```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 the thread's run state. `subscribe()` publishes a
map of every active run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.