Tracked changes with comments

Separate product

Tracked Changes 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 extension is currently in Alpha phase.

Continuation from the Use with Tracked Changes guide

This guide continues the Use with 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. This guide builds on the Use with Tracked Changes integration and requires the separately licensed Tracked Changes 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.

PreviouslyWith Tracked Changes

Next upSuggestions