Annotations

Annotations are a red pen for AI output. Select rendered text in the preview and mark it up with strikes, locks, comments, notes, and block instructions, then copy your annotations as a structured prompt for any AI assistant.

Annotations work in viewer mode only. Enter edit mode to make changes yourself, or use annotations to describe what an AI tool should change.

Annotation Types

There are five annotation types:

  • Strike — Select text and click Strike on the floating toolbar, or press S. Marks the text for deletion with a red strikethrough. Use this when text should be removed entirely.
  • Lock — Select text and click Lock on the floating toolbar, or press L. Highlights the text in green to protect it from changes. Use this when text should remain exactly as-is.
  • Comment — Select text and click Comment on the floating toolbar, or press C, then type your suggestion. Highlights the text in yellow with your editing instruction attached. Use this when text should be rewritten or changed.
  • Note — Add a document-level note with ⌘⇧N. Notes are not tied to specific text. Use this for general instructions like "add a conclusion section" or "change the tone to be more formal."
  • Block Note — Press ⌘⇧B to enter block note mode. Block-level elements (paragraphs, headings, lists, code blocks) become selectable. Click a block, then type an instruction about the surrounding text. Use this to give AI tools block-level directions.

When you select text in the preview, a floating toolbar appears with buttons for Strike, Lock, Comment, and Delete. You can also use keyboard shortcuts while the toolbar is visible: S for strike, L for lock, C for comment, X to delete the annotation.

Annotation Toolbar

Toggle the annotation toolbar with ⌘⇧A or the toolbar button. The toolbar is an inline strip that slides down below the window title bar with buttons for the document note, block note, copy/export, delete all, and done, plus a count of annotations. The toolbar button displays a badge with the total annotation count.

The document note has its own panel — click the note icon in the annotation toolbar to toggle it. It appears as a sticky note below the toolbar where you can type instructions that aren't tied to specific text.

Copying Annotations

Press ⌘⌥⇧C to copy your annotations. Peekdown copies a structured prompt to your clipboard that includes all your annotations formatted for AI assistants. The format uses a JSON array where each annotation has a type field (delete, lock, comment, note, or blocknote) with before and after context fields so AI assistants can locate and parse the exact text.

Paste the prompt into whichever AI you use — Claude Code, Cursor, ChatGPT, Claude.ai, or any other assistant. In a terminal, pbpaste | claude (or your tool's equivalent) pipes the clipboard straight into the conversation.

After copying, Peekdown clears the annotations from your document so the AI's response can be applied to a clean version. If you change your mind — say the AI's edit isn't what you wanted — press ⌘⌥⇧Z, choose Edit > Restore Annotations, or click the Restore button in the annotation toolbar to bring your annotations back. The snapshot persists across restarts and survives closing the file, so you can restore even days later. Each Copy creates a new snapshot, replacing the previous one.

Restore is automatically discarded once the document changes. If your AI assistant applies the edits and saves the file (or you edit it yourself), the snapshot no longer matches the document and Peekdown discards it — the Restore button disappears and the menu item becomes disabled. This is intentional: restoring annotations onto modified text would put them in the wrong place. If you want a permanent backup of your annotations regardless of what happens to the document, export them first via Edit > Export Annotations (⌘⌥⇧E) — that writes a .json file next to your document that you can re-import any time, even after the document has been edited.

Persistence

Annotations are automatically saved to the app's storage at ~/Library/Application Support/Peekdown/annotations/. When you reopen a file, its annotations are restored automatically. When you switch to a different file with unexported annotations, Peekdown shows a reminder that your annotations are saved and will be restored when you return.

Import & Export Files

You can export annotations to and import them from standard JSON files using the Edit menu.

Export Annotations (Edit > Export Annotations) saves a .json file alongside your document. The naming convention is filename.json — for example, annotations for notes.md are saved as notes.json. The file is a standard JSON file, visible in Finder, that you can share with collaborators or back up alongside your documents.

Import Annotations (Edit > Import Annotations) opens a file picker for .json annotation files. You can also drag and drop a .json annotation file directly onto the Peekdown window to import it. When you import annotations, they are saved to Peekdown's internal storage. From that point on, the annotations persist in Peekdown automatically — you don't need to keep the JSON file. If you close and reopen the document later, your imported annotations will still be there.

File Format

Annotation files use JSON with the following schema:

{
  "annotations": [
    {
      "id": 1,
      "type": "strike",
      "text": "text to delete",
      "contextBefore": "preceding context",
      "contextAfter": "following context"
    },
    {
      "id": 2,
      "type": "lock",
      "text": "text to preserve",
      "contextBefore": "...",
      "contextAfter": "..."
    },
    {
      "id": 3,
      "type": "comment",
      "text": "text to change",
      "comment": "editing instruction",
      "contextBefore": "...",
      "contextAfter": "..."
    },
    {
      "id": 4,
      "type": "note",
      "text": "document-level instruction"
    },
    {
      "id": 5,
      "type": "blocknote",
      "text": "instruction for this block",
      "blockText": "the block this note applies to",
      "contextBefore": "...",
      "contextAfter": "..."
    }
  ],
  "nextId": 6,
  "hasUnexported": false,
  "exportedContentHash": "sha256-hex-string"
}

The type field must be one of: strike, lock, comment, note, or blocknote. The contextBefore and contextAfter fields anchor annotations to surrounding text so they survive minor edits. The exportedContentHash lets Peekdown detect when the document has been updated by an AI tool after export.