Skip to main content
Use plannotator annotate to open a supported document or plain-text config file, a web page, or a folder.

​
Open a Markdown or text document

When you run the command directly, Plannotator starts a temporary local server, opens the annotation UI, and waits for your response. Send Feedback prints formatted feedback to stdout. Agent skills and commands return the same feedback to the active agent session. Add --gate when the document needs an explicit approval decision:

​
Open a folder

Pass a folder to open the file browser:
The browser lists the same supported local formats as direct file annotation:
  • documents: .md, .mdx, and .txt
  • plain-text config and data: .yaml, .yml, .json, .jsonc, .json5, .toml, .ini, .cfg, .conf, .properties, .csv, .tsv, .log, .xml, and .env.example
  • HTML: .html and .htm
Plain-text config and data files keep their content unchanged and use the standard text annotation view. A bare .env file is excluded because it commonly contains secrets and annotation history can store content copies. Source-code extensions are excluded; use code review for them. Only Markdown and MDX use Markdown frontmatter rules. A supported non-Markdown file that begins with --- keeps those lines as document content. Each local file must be 2 MiB or smaller. Select a file to annotate it, then move to another file without starting a new Plannotator session. Common generated and dependency directories, including node_modules, dist, and build, are skipped. See Annotate a Folder for file-browser shortcuts, folder feedback, and large-folder limits. In rendered Markdown, Plannotator opens relative links to .md, .mdx, .txt, .html, and .htm files inside the same review UI. It also opens [[wiki-links]]; a wiki-link without an extension resolves as a Markdown file. Relative paths are resolved from the active document. Use the file badge or sidebar to return to the previous document. Annotations on linked documents are included when you send the review’s combined feedback. Links to a heading in another local document open the document but do not scroll to that heading. Plannotator strips the link fragment before opening the linked document. A file selected from a folder can receive per-file version history, while an ordinary document opened only through a link does not. See Version history.

​
Open a web page

Plannotator converts web pages to Markdown before annotation. Jina Reader is used by default for public pages. URLs on localhost or private networks use a direct fetch because Jina cannot reach them. Use direct fetch for any URL with --no-jina:
Direct fetch converts the returned HTML with Turndown. URLs ending in .md or .mdx are read as text when the response is Markdown.
Plannotator annotates an imported copy of a web page, not the live page. For live-site annotation, use App Notes in the Chrome Web Store. The latest GitHub release provides separate Chrome and Firefox packages with checksums.

​
Edit Markdown

The Markdown editor supports two outcomes:
  • For a plan, agent message, URL conversion, or other non-writable source, Plannotator sends your changes to the agent as a unified diff.
  • For an eligible local Markdown, MDX, or supported plain-text file, save with Cmd/Ctrl+S to replace the file atomically. Plannotator confines the write to the opened source file, checks whether it changed on disk, and asks you to resolve a conflict when needed.
Saved file changes are included with submitted feedback as context so the agent knows they are already applied. Unsaved edits are not written to disk. Local HTML has its own rendered workflow. See Annotate HTML. To change the message returned by supported agent wrappers, see Customize Feedback. Last verified on July 31, 2026, using Plannotator product commit 7cd023c. Maintained by the Plannotator project.
Last modified on August 9, 2026