Promptuary

An Obsidian plugin for reading annotations and AI-powered batch review. Highlight and take notes while reading, leave review comments, then hand them off to external AI agents for execution — all in one click.

中文文档

Target Users & Scenarios

Who is it for

• Product managers / Editors / Writers: Review product docs, proposals, weekly reports — lots of small tweaks, but don't want to edit each one manually
• Researchers: Mark key points and add thoughts while reading papers / reports
• Team leads: Give revision feedback on team members' documents
• Developers: Review tech docs, READMEs, PRDs — high overlap with CLI Agent users

What problem does it solve

When reading and reviewing documents in Obsidian, ideas and revision notes end up scattered across your mind or chat windows. It's hard to capture them at low cost, aggregate them, and hand them to AI for batch execution. Existing highlight / note plugins stop at "annotation recording" — none bridge the gap from reading annotations → review comments → external AI modification.

Key Features

Reading Mode

• 4-color highlights: Select text → click a color → instant highlight, no modification to the original file (stored in sidecar JSON)
• Reading notes: Select text → click Note to expand the input area → add text notes, bound to the original text

Review Mode

• Strikethrough (Delete): One click to mark text as "strongly delete / merge" intent
• Natural language review comments: Click Note to expand the input area, write things like "make this more conversational" or "add an example here" — no forced categorization
• Sidebar review list: All comments aggregated, with jump / edit / delete support

Floating Toolbar

Select text and a floating toolbar appears with a vertical three-section layout:

1. Mode capsule: Top [Reading] / [Review] quick switch
2. Button row: Reading mode → 4 color highlights + Note; Review mode → Delete + Note
3. Note expansion area: Click Note to expand downward, with color marker + label + input field + Save

AI Execution (Four Paths)

Diff Preview & Auto-Reanchoring (Desktop)

After AI or API modifies a file, the plugin automatically compares differences and offers Accept All / Accept by Chunk / Rollback.

After confirmation, annotation positions are automatically re-anchored:

1. Strategy B (Diff re-anchor): Compute old offset → new offset mapping based on LCS diff, precise update
2. Strategy A (fuzzy locate fallback): Edit distance + trigram similarity sliding window, auto-repair drifted annotations
3. Executed review comments are automatically removed; invalid reading annotations auto-cleaned

Getting Started

1. Installation

Obsidian Community Plugins (Recommended)

Promptuary is available on the Obsidian Community Plugins marketplace:

1. Open Settings → Community plugins
2. Turn off Restricted mode if you haven't already
3. Click Browse → search for "Promptuary"
4. Click Install, then Enable

Manual install (for pre-release / development builds):

git clone https://github.com/meganjjzhang/Promptuary
cd Promptuary
npm install
npm run build

Copy main.js, manifest.json, and styles.css to your Vault's .obsidian/plugins/promptuary/ directory, then restart Obsidian and enable the plugin under Settings → Community plugins.

2. Reading Annotations

1. Open any Markdown file
2. Click the highlighter icon in the left Ribbon, or search "Open Promptuary Sidebar" in the Command Palette
3. Select the Reading capsule at the top
4. Select text → floating toolbar appears with mode capsule + color buttons → click a color to highlight
5. Click Note to expand the input area, add text notes, then click Save

3. Reviewing Documents

1. Switch the floating toolbar or sidebar top capsule to Review
2. Select the text you want to revise
3. Click Delete to toggle strikethrough (click again to remove), or click Note to expand the input area and write review comments
4. All comments are aggregated in the sidebar review list

4. Export for AI Execution

Method A: Export File / Copy Prompt (All platforms)

Click "Export Review File" or "Copy Prompt" at the bottom of the sidebar, then upload the generated Markdown instruction file to any AI tool like ChatGPT, Claude Web, etc.

Method B: CLI One-Click Execution (Desktop)

First install any Agent CLI:

npm i -g @anthropic-ai/claude-code   # Claude Code
npm i -g @openai/codex               # Codex CLI
pip install aider-chat               # Aider
npm i -g @google/gemini-cli          # Gemini CLI

Click an Agent button at the bottom of the sidebar → select an installed Agent → confirm command → terminal auto-executes → Diff preview pops up after completion.

Uninstalled Agent buttons appear grayed out; clicking copies the command to clipboard for manual execution.

Method C: API Key Direct Call (Desktop)

No CLI tools needed — call model APIs directly from within the plugin.

1. Open Settings → API Direct Call
2. Select Provider (Anthropic / OpenAI / DeepSeek / Gemini / Custom Endpoint)
3. Enter API Key and model name
4. Click "Test" to verify the connection
5. Search "API Key Direct Call Execute" in the Command Palette (Cmd+P) or use the sidebar button
6. Confirm the privacy notice → plugin calls API → Diff preview auto-pops up

5. Diff Preview & Confirmation

After AI executes modifications, the plugin displays line-by-line differences:

• Accept All: Keep all AI modifications
• Accept by Chunk: Select which modification chunks to keep
• Rollback: Restore original text, discard all changes

After confirmation, annotations are automatically re-anchored and executed review comments are removed.

Settings

General

Agent & Terminal (Desktop)

Predefined Agents (5):

Available template variables: {{vaultPath}} {{instructionFile}} {{filePath}} {{fileName}} {{prompt}}

API Direct Call (Desktop)

Supported AI Tools

Platform Support

Mobile uses a bottom toolbar (BottomToolbar) instead of the desktop floating toolbar to avoid conflicts with iOS/Android system selection menus.

Data Storage

Annotations are stored as sidecar JSON in the .promptuary/annotations/ directory — original Markdown files are never modified.

vault/
├── .promptuary/
│   ├── annotations/    # Annotation data (one JSON per file)
│   └── exports/         # Exported review instruction files
├── your-doc.md         # Original file is untouched

Annotation JSON structure (AnnotationFile):

{
  "version": 1,
  "filePath": "path/to/doc.md",
  "baselineHash": "sha256...",
  "annotations": [
    {
      "id": "ann_xxx",
      "type": "highlight | note | review",
      "selectedText": "selected text",
      "contextBefore": "...",
      "contextAfter": "...",
      "lineHint": 5,
      "occurrenceIndex": 0,
      "highlightColor": "yellow | blue | green | purple",
      "noteText": "reading note content",
      "reviewText": "review comment content",
      "strike": false
    }
  ]
}

API Keys are stored only in Obsidian's local plugin data (this.saveData()), never uploaded, never proxied.

Anchor Positioning

Annotations do not store offsets (from/to); positions are computed dynamically at load time via text search:

1. Exact match: selectedText is unique in the document → direct positioning
2. occurrenceIndex + lineHint disambiguation: Repeated paragraphs use occurrence sequence + line hint
3. Fuzzy locate (fuzzyLocate): Edit distance + trigram similarity sliding window
4. Drift detection: baselineHash comparison, auto-alert when document changes
5. Auto-repair: After Agent Diff confirmation, auto-reanchor (Strategy B + Strategy A fallback)

Version Roadmap

Command Palette Shortcuts