Tracked changes with comments

Experimental

The Tracked Changes extension is currently in Alpha phase.

Continuation from the tracked changes guide

This guide continues the tracked changes guide. 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 extension.

See the source code on GitHub.

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.

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

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

See the source code on GitHub.

Next steps

Learn more about review options in the API reference.
Add real-time streaming with the streaming guide.
Learn about the Tracked Changes extension for styling and configuration options.
Learn about the Comments extension for comments configuration and styling.

PreviouslyTracked changes

Next upSuggestions