Annotation types
Find Global Comment
In a rendered Markdown plan or document, Global comment is in the document action bar. On a narrower layout, its label shortens to Comment or to an icon. It is not shown while the Markdown editor or rendered Markdown diff replaces the normal document view. In rendered HTML, the equivalent action is labeled Comment. Selecting Hide tools hides this action with the other HTML annotation controls. Ordinary rendered Markdown annotate sessions do not intentionally hide Global Comment. If the full text label is missing, look for Comment or the speech-bubble icon with the Add global comment tooltip. Plannotator chooses the full, short, or icon-only label from the current width of the document action bar. The standalone archive is read-only. It hides Global Comment, Attachments, selection composers, direct-edit and notes-save actions, and other document mutation controls. Linked documents opened from the archive remain read-only. Both the Bun and Pi servers also reject archive mutation requests, so this boundary does not depend on a client-side flag.Attach and mark up images
You can paste or upload an image into a comment or use Images for a document-level attachment. Plannotator stores an uploaded image as a temporary local file and includes its name and path in the feedback sent to the agent. Open an attached image to draw with the pen, arrow, or circle tools. Drawing applies only to that image. Plannotator does not provide a freehand layer over Markdown, rendered HTML, or code diffs.Make a direct edit
Open the Markdown editor when rewriting the text is clearer than describing the change. Plannotator records added and removed lines and includes a unified diff in the feedback. Eligible local Markdown, MDX, and text files can also be saved to disk withCmd/Ctrl+S. The feedback marks those changes as already applied so the agent does not repeat them. See Annotate documents for the write and conflict behavior.
Check feedback before sending
Open Export and select Annotations to inspect the generated Markdown. You can copy it or downloadannotations.md without ending the review.
The exported feedback can include:
- source line labels and selected text
- comments, deletions, quick labels, and general feedback
- attached image paths
- direct-edit diffs and file changes already saved to disk
- a marker when an annotation refers to a changed block in the version diff
Choose the review decision
If pending feedback would be dropped by Approve or Close, Plannotator opens a warning. Choose Cancel to keep the session and its pending feedback open.
--gate adds Approve, but it does not make every other decision fail the calling process. In hook-native mode, Approve and Close both produce empty output, which lets the host hook pass. Use direct --gate --json --require-approval when approval must be the only successful outcome. See Approval gates and automation hooks.
Know where feedback goes
When a supported agent opens Plannotator, Send Feedback returns the generated feedback to that agent session. A direct CLI run prints it to standard output. The embedded terminal is different. Starting it launches a new local agent CLI process in the review’s working directory. When that terminal is ready, Send Feedback goes to the new agent and the Plannotator window stays open. It does not reconnect to or deliver feedback to the original agent that opened the review. Plannotator does not keep a completed OSS review session attached to the original agent across multiple feedback rounds.End or reopen a session
Send Feedback, Approve, and Close normally end the temporary local server. If the agent revises the content and opens Plannotator again, that is a new review session. The completed page can remain visible when Auto-close Tab is off; change that browser preference in Settings > General. Draft annotations and direct edits are saved under the Plannotator data directory while a session is open, so a server or browser interruption can restore them.plannotator sessions --open can reopen a server that is still running. Draft recovery, version history, and reopening a live server do not restore a completed connection to the original agent.
Last verified on August 1, 2026, using Plannotator product commit d53cbfb. Maintained by the Plannotator project.