Tiptap Docs

Use with Tracked Changes

Display server-side AI edits as tracked changes, so your users can review and accept or reject them individually. This integrates the Server AI Toolkit with the Tracked Changes extension.

Separate product

Tracked Changes is a separate Tiptap product from the Server AI Toolkit, sold separately. It handles user edits by default and can review AI edits when integrated with the Server AI Toolkit.

See the source code on GitHub.

Experimental

The Tracked Changes extension is currently in Alpha phase.

Continuation from the AI agent chatbot guide

This guide continues the AI agent chatbot guide. Read it first.

How it works

  1. The AI reads the document with tiptapRead in trackedChanges mode.
  2. The AI edits the document with tiptapEdit in trackedChanges mode.
  3. The Server AI Toolkit writes tracked change marks through the Tracked Changes extension instead of directly mutating the document.
  4. The client displays the tracked changes with the Tracked Changes extension and lets users accept or reject them.

Show tracked changes

To display server-side AI edits as tracked changes, configure the reviewOptions parameter on the POST /v3/toolkit/execute-tool endpoint. Set the review mode to {mode: 'trackedChanges'}, when calling both the tiptapRead and tiptapEdit tools. See the review options reference for all available settings.

Execute tools with tracked changes

Pass reviewOptions when calling execute-tool:

import { getAuthHeaders } from '@/lib/server-ai-toolkit/get-auth-headers'

const result = await fetch(`${apiBaseUrl}/toolkit/execute-tool`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    toolName: 'tiptapEdit',
    input: toolCallInput,
    editorContext,
    experimental_documentOptions: {
      documentId: 'your-document-id',
      userId: 'ai-assistant',
    },
    reviewOptions: {
      mode: 'trackedChanges',
      trackedChangesOptions: {
        userId: 'ai-assistant',
        userMetadata: {
          name: 'AI Assistant',
        },
      },
    },
  }),
})

See the review options reference for the full reviewOptions shape, including trackedChangesOptions and diffUtilityOptions.

Client-side setup

On the client, install and add the ServerAiToolkit and TrackedChanges extensions.

import { useChat } from '@ai-sdk/react'
import { Collaboration } from '@tiptap/extension-collaboration'
import { EditorContent, useEditor } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import { TrackedChanges, findSuggestions } from '@tiptap-pro/extension-tracked-changes'
import { TiptapCollabProvider } from '@tiptap-pro/provider'
import { ServerAiToolkit, getEditorContext } from '@tiptap/server-ai-toolkit'

export default function Page() {
  const editor = useEditor({
    immediatelyRender: false,
    extensions: [
      StarterKit.configure({ undoRedo: false }),
      Collaboration.configure({ document: doc }),
      TrackedChanges.configure({ enabled: false }),
      ServerAiToolkit,
    ],
  })

  // ... render editor and chat UI
}

After the AI edits the document, the changes appear as tracked changes. Users can accept or reject them using the acceptSuggestion, rejectSuggestion, acceptAllSuggestions, and rejectAllSuggestions commands from the Tracked Changes extension.

See the source code on GitHub.

Add comments with tracked changes

See the source code on GitHub.

You can make the AI provide a justification for each change. Each justification becomes a comment thread linked to its tracked change, using the Comments extension.

API endpoint

When fetching tool definitions, configure the tiptapEdit tool so it can include a meta field on operations. Then instruct the AI to provide a justification in that meta field.

const response = await fetch(`${apiBaseUrl}/toolkit/tools`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    editorContext,
    tools: {
      tiptapEdit: true,
    },
    operationMeta: 'Brief justification explaining why this change improves the document.',
  }),
})

Execute tools with comments

Pass experimental_commentsOptions alongside reviewOptions when calling execute-tool:

const result = await fetch(`${apiBaseUrl}/toolkit/execute-tool`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    toolName: 'tiptapEdit',
    input: toolCallInput,
    editorContext,
    experimental_documentOptions: {
      documentId: 'your-document-id',
      userId: 'ai-assistant',
    },
    reviewOptions: {
      mode: 'trackedChanges',
      trackedChangesOptions: {
        userId: 'ai-assistant',
        userMetadata: {
          name: 'AI Assistant',
        },
      },
    },
    experimental_commentsOptions: {
      threadData: { userName: 'Tiptap AI' },
      commentData: { userName: 'Tiptap AI' },
    },
  }),
})

Each non-empty meta field in the edit operations becomes a comment thread linked to its tracked change. The justification is stored as the thread's first comment content and as suggestionReason in the thread data.

Client-side setup

On the client, add the CommentsKit extension with a TiptapCollabProvider:

import { CommentsKit } from '@tiptap-pro/extension-comments'
import { TrackedChanges } from '@tiptap-pro/extension-tracked-changes'
import { ServerAiToolkit } from '@tiptap/server-ai-toolkit'

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

Users can review the tracked change and read the AI's justification in the comments sidebar.

See the source code on GitHub.

Next steps

PreviouslyAI agent chatbot