Selection awareness

Make AI aware of the user's selected content, so it can edit it.

See the source code on GitHub.

The readSelection tool

With the readSelection tool, the AI can read the user's selection. This tool only works with Tiptap Cloud collaborative documents.

Enable it in the fetch-tools request alongside the other tools:

const response = await fetch(`${apiBaseUrl}/v4/ai/toolkit/fetch-tools`, {
  method: 'POST',
  headers: await getAuthHeaders(),
  body: JSON.stringify({
    editorContext,
    tools: {
      readSelection: true,
      // Other tools
      tiptapRead: true,
      tiptapEdit: true,
    },
  }),
})

The readSelection tool reads the selection of a single user. This is usually the user who prompts the AI. Pass the user ID as the tool.config.user parameter when the tool is executed. The developer passes this parameter, so the AI does not generate it.

const response = await fetch(`${apiBaseUrl}/v4/ai/toolkit/execute-tool`, {
  method: 'POST',
  headers: await getAuthHeaders(documentId),
  body: JSON.stringify({
    editorContext,
    document: { type: 'cloud', id: documentId },
    tool: {
      name: 'readSelection',
      // The AI calls the readSelection tool with no input parameters
      input: {},
      // The user's ID is passed by the developer
      config: { user: 'user-1' },
    },
  }),
})

See the REST API reference for more details about the tool.

Publish the selection to awareness

The server reads the selection from live collaboration awareness data. To make this data available, configure the CollaborationCaret extension and give the user an id that matches the tool.config.user you send to the server. Create the editor once the provider is connected so the caret can attach.

import { CollaborationCaret } from '@tiptap/extension-collaboration-caret'

const editor = useEditor({
  extensions: [
    StarterKit,
    Collaboration.configure({ document: doc }),
    CollaborationCaret.configure({
      provider,
      // The id is what readSelection matches against on the server.
      user: { id: 'user-1', name: 'You', color: '#6a00f5' },
    }),
    ServerAiToolkit,
  ],
})

Preserving the selection

The server reads the selection from awareness at the moment the tool runs. CollaborationCaret clears the awareness selection when the editor loses focus, so if the user clicks into a chat input before sending, the server reads an empty selection.

Re-focus the editor when the user sends a message so CollaborationCaret re-publishes the current selection:

const handleSubmit = () => {
  if (!input.trim()) return
  // Re-publish the selection to awareness: moving to the chat input blurred the
  // editor and cleared the awareness cursor.
  editor.commands.focus()
  sendMessage({ text: input })
  setInput('')
}

End result

With additional CSS styles, the result is a chatbot that can edit the user's selection:

See the source code on GitHub.

Limitations

Only works with Tiptap Cloud documents on the default field

The readSelection tool reads the selection state from the live updates sent by the CollaborationCaret extension. Therefore, it only works with Tiptap Cloud collaborative documents and is not compatible with documents provided inline.

An advanced option of collaborative documents is to store multiple fields. Currently, the readSelection tool only supports the default field. If you have a use case that involves multiple fields, contact us.

AI model behavior

readSelection tells AI what content is selected, but it does not force it to edit only the selection. Smaller, less capable AI models may rewrite the surrounding paragraph instead of just the selected span, especially for a sub-sentence selection.

In our testing, models with reasoning enabled (for example, gpt-5.4-mini with reasoning effort set to low) keep their edits scoped to the selection more reliably. A clear instruction such as "edit only the selected text" also helps.

Next steps

• Read the readSelection REST API reference
• Add more capabilities to your agent by following the guides in the Agents section