Creating annotations with the Chat tool

Annotations give your agent a specific target and your intent. Chat lets you discuss the work, and threads keep the feedback, replies, and follow-ups together so you can iterate without re-explaining the page.

Leave a comment

Choose Chat (C) and click an element. Type your feedback, then press Enter to finish the draft. Shift+Enter adds a new line. Paste an image into the comment to attach a visual reference.

Shake your mouse to quickly switch between Chat and Steer, so you can move between leaving feedback and tweaking styles.

You can leave several comments before sending. Command/Control+Enter hands off the whole pending bundle, including staged Steer changes and direct text edits, as one thread. See Tweaking styles with the Steer tool for the styling workflow.

Draft comments are not submitted instructions. Finishing a draft or previewing a change does not start an agent run.

Edit text directly

Double-click visible text in Chat mode to edit it on the page. The edit becomes part of your pending work; send it when you want your agent to implement it in the codebase.

Annotate images and paused video

Manual media annotation is part of Core and is enabled by default. It does not require See, object segmentation, or a vision-model download.

In Chat mode, drag over an image to create a named object. The same interaction works on a paused video.

• Single-click an object to comment on it.
• Double-click an object to rename or resize it.
• Right-click its label to delete it.

Image targets stay aligned as the image resizes. A manual video box stays at its saved position unless a perception extension supplies motion tracking. To add recognition with See, read Annotating static objects in images. To follow an object through video, read Annotating moving objects in video.

Configure media annotation

Use imageAnnotation={false} or videoAnnotation={false} on PopmeltProvider to disable either capability. To limit eligible images:

<PopmeltProvider imageAnnotation={{ selector: 'img[data-popmelt-media]' }}>
  {children}
</PopmeltProvider>

Give media a stable identity when its URL may change or the same source appears more than once:

<img data-popmelt-media-id="hero-product" src={imageUrl} alt="Product" />
<video data-popmelt-media-id="hero-reel" src={videoUrl} controls />

Media-object stores are browser-local by default. Supply imageAnnotation.store or videoAnnotation.store when targets must survive browser-site-data removal or move between origins. Extension-produced tracks remain replayable through Core after the extension is disabled.

For objects in a Three.js scene, see Using Popmelt with Three.js and react-three-fiber.

Continue the conversation

Click an annotation or status badge to reopen its thread. The thread keeps the original targets and evidence with the replies, so a follow-up such as “A little less padding” has context.

• Use the header chevrons to cycle through visible threads.
• Drag the header to reposition a thread; double-click it to restore its default position.
• Press Escape to close the panel without archiving the conversation.
• If a follow-up is queued, use its pencil or trash button to edit or delete that message before it starts. Save an edit with the checkmark or Command/Control+Enter; Escape cancels it.

Approvals and review

Codex permission requests appear in the thread. Expand the request to inspect the command or file changes, then choose Allow once or Deny. Answered requests remain in the conversation history.

Typing “go ahead” in chat is not a permission grant. Existing Codex permission rules still apply; previously allowed actions may not show a new approval card. Interactive approvals require a compatible Codex CLI.

Your agent can edit files and run commands. Review the diff and run your project's tests before shipping.

Clear a draft, dismiss a rail, or archive a thread

These actions do different things:

• Remove a draft: right-click a draft comment or staged change in its rail to remove only that item.
• Dismiss a replied rail: right-click it to hide it from the canvas without deleting history or reverting implemented changes. Command/Control+Z outside a text editor restores it before a reload. Fresh drafts and active runs are protected.
• Archive a thread: press Backspace/Delete while its panel is open or a historical annotation is selected. Archiving hides it from the active canvas but retains the stored conversation.

Delete shortcuts leave focused text fields alone.

What is saved

Thread history, screenshots, and Imprint live with the project under .popmelt/. Unsent drafts and preview state use origin-scoped browser storage. When you send work, the required context goes to your chosen AI provider under that provider's privacy policy.

For application-owned context such as document IDs, data revisions, or video frame times, see Add custom context to Popmelt annotations and threads. Core can attach a snapshot to the corresponding human turn with getCommentMeta.

Next: Tweaking styles with the Steer tool or Helping your AI understand your taste with the Imprint tool.