---
title: "Tracked changes with comments"
description: "Combine AI-generated tracked changes with comment threads that explain each change."
canonical_url: "https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/agents/review-changes/tracked-changes-with-comments"
---

# Tracked changes with comments

Combine AI-generated tracked changes with comment threads that explain each change.

> **Separate product:**
>
> [Tracked Changes](https://tiptap.dev/docs/tracked-changes/getting-started/overview.md) is a separate Tiptap product from the AI Toolkit, sold separately. It handles user edits by default and can review AI edits when integrated with the AI Toolkit.

> **Experimental:**
>
> The [Tracked Changes](https://tiptap.dev/docs/tracked-changes/getting-started/overview.md) extension is currently in Alpha phase.

> **Continuation from the Use with Tracked Changes guide:**
>
> This guide continues the [Use with Tracked Changes
> guide](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/agents/review-changes/tracked-changes.md). Read it first.

You can ask the AI to provide a justification for each change. Each justification becomes a comment thread linked to its tracked change, using the [Comments](https://tiptap.dev/docs/comments/getting-started/overview.md) extension. This guide builds on the [Use with Tracked Changes](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/agents/review-changes/tracked-changes.md) integration and requires the separately licensed Tracked Changes extension.

> **Interactive demo:** [tracked changes comments](https://ai-toolkit-demos.vercel.app/tracked-changes-comments)

See the [source code on GitHub](https://github.com/ueberdosis/ai-toolkit-demos).

## API endpoint

On the server, pass the `operationMeta` option to `toolDefinitions` to add a `meta` field to edit operations. Then instruct the AI to provide a justification in the `meta` field.

```ts
// app/api/tracked-changes-comments/route.ts
import { openai } from '@ai-sdk/openai'
import { toolDefinitions } from '@tiptap-pro/ai-toolkit-ai-sdk'
import { createAgentUIStreamResponse, ToolLoopAgent, type UIMessage } from 'ai'

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json()

  const agent = new ToolLoopAgent({
    model: openai('gpt-5.4-mini'),
    instructions: `You are an assistant that can edit rich text documents.
Rule: Use tiptapRead before tiptapEdit.
Rule: When editing the document, ALWAYS provide a brief justification for each change in the meta field.`,
    tools: toolDefinitions({
      operationMeta:
        'Brief justification explaining why this change improves the document.',
    }),
  })

  return createAgentUIStreamResponse({
    agent,
    uiMessages: messages,
  })
}
```

## Client-side setup

On the client, add the `CommentsKit` extension and pass `commentsOptions` to the `executeTool` method. The `commentsOptions` property configures the thread and comment metadata for the AI-generated comments.

```tsx
import { AiToolkit, getAiToolkit } from '@tiptap-pro/ai-toolkit'
import { CommentsKit } from '@tiptap-pro/extension-comments'
import { TrackedChanges } from '@tiptap-pro/extension-tracked-changes'

const editor = useEditor({
  extensions: [
    StarterKit,
    TrackedChanges.configure({ enabled: false }),
    AiToolkit,
    CommentsKit.configure({
      provider, // Your TiptapCollabProvider instance
    }),
  ],
})

// Inside onToolCall:
const result = toolkit.executeTool({
  toolName: toolCall.toolName,
  input: toolCall.input,
  reviewOptions: {
    mode: 'trackedChanges',
    trackedChangesOptions: {
      userId: 'ai-assistant',
      userMetadata: { name: 'AI' },
    },
  },
  commentsOptions: {
    threadData: { userName: 'AI' },
    commentData: { userName: 'AI' },
  },
})
```

Each non-empty `meta` field in the edit operations becomes a comment thread linked to its tracked change. Users can review the change and read the AI's justification in the comments sidebar.

## End result

> **Interactive demo:** [tracked changes comments](https://ai-toolkit-demos.vercel.app/tracked-changes-comments)

See the [source code on GitHub](https://github.com/ueberdosis/ai-toolkit-demos).

## Next steps

- Learn more about [review options](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/review-options.md) in the API reference.
- Add real-time streaming with the [streaming guide](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/agents/streaming.md).
- Learn about the [Tracked Changes](https://tiptap.dev/docs/tracked-changes/getting-started/overview.md) extension for styling and configuration options.
- Learn about the [Comments](https://tiptap.dev/docs/comments/getting-started/overview.md) extension for comments configuration and styling.