Michael Ramos
72b8ae069d
Adds a config-only `markdownExtensions` key to ~/.plannotator/config.json,
e.g. { "markdownExtensions": [".livemd"] } for Livebook notebooks. A listed
extension is accepted everywhere .md is on the annotate path: CLI target
resolution, folder discovery and the file browser, /api/doc plus relative and
wiki-link navigation between sibling docs, the 2MB size cap, and per-file
version history. Listed extensions render as markdown with frontmatter
stripped, never as raw HTML, and they only widen the accepted set.
Design:
- packages/core/annotatable.ts stays browser-safe and zero-dep. Its regexes
and predicates now take an optional, defaulted-empty list of extra
extensions, plus a normalizer and regex builders.
- packages/shared/markdown-extensions.ts is the node-side seam: it reads
config.json once per process through the existing loadConfig() and threads
the normalized list into those pure functions. resolve-file re-exports the
config-aware predicates so both runtimes pick them up; the Bun server, the
Pi mirror, the OpenCode plugin and the CLI all go through them.
- The annotate /api/plan payload ships the resolved list so the renderer can
linkify links to sibling documents (module-level UI registry, empty by
default, so nothing changes without config).
Validation: entries must be dot-led, lowercase-normalized, and free of path
separators, globs and whitespace. Invalid entries are dropped silently,
built-ins are deduplicated, and `.env` is denylisted so config can never
register it (annotate copies file contents into the data dir).
Deliberately unchanged: the Pi plan-write allowlist (ALLOWED_PLAN_EXTENSIONS
in tool-scope.ts) and Edit Mode source save (SOURCE_SAVE_FILE_REGEX), which
keep their own narrower allowlists.
Plannotator Claude Code Plugin
This directory contains the Claude Code plugin configuration for Plannotator.
Prerequisites
Install the plannotator command so Claude Code can use it:
macOS / Linux / WSL:
curl -fsSL https://plannotator.ai/install.sh | bash
Windows PowerShell:
irm https://plannotator.ai/install.ps1 | iex
Windows CMD:
curl -fsSL https://plannotator.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Released binaries ship with SHA256 sidecars and SLSA build provenance attestations from v0.17.2 onwards. See the installation docs for version pinning and the verification docs for verification commands.
Plugin Installation · Manual Installation (Hooks) · Obsidian Integration
Plugin Installation
In Claude Code:
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator
Important: Restart Claude Code after installing the plugin for the hooks to take effect.
Manual Installation (Hooks)
If you prefer not to use the plugin system, add this to your ~/.claude/settings.json:
{
"hooks": {
"PermissionRequest": [
{
"matcher": "ExitPlanMode",
"hooks": [
{
"type": "command",
"command": "plannotator",
"timeout": 345600
}
]
}
]
}
}
How It Works
When Claude Code calls ExitPlanMode, this hook intercepts and:
- Opens Plannotator UI in your browser
- Lets you annotate the plan visually
- Approve → Claude proceeds with implementation
- Request changes → Your annotations are sent back to Claude
- On resubmission → Plan Diff shows what changed since the last version
Environment Variables
| Variable | Description |
|---|---|
PLANNOTATOR_REMOTE |
Set to 1 / true for remote mode, 0 / false for local mode, or leave unset for SSH auto-detection. Uses a fixed port in remote mode; browser-opening behavior depends on the environment. |
PLANNOTATOR_PORT |
Fixed port to use. Default: random locally, 19432 for remote sessions. |
PLANNOTATOR_BROWSER |
Custom browser to open plans in. macOS: app name or path. Linux/Windows: executable path. |
PLANNOTATOR_SHARE_URL |
Custom share portal URL for self-hosting. Default: https://share.plannotator.ai. |
Remote / Devcontainer Usage
When running Claude Code in a remote environment (SSH, devcontainer, WSL), set PLANNOTATOR_REMOTE=1 (or true) and these environment variables:
export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=9999 # Choose a port you'll forward
This tells Plannotator to:
- Use a fixed port instead of a random one (so you can set up port forwarding)
- Use remote-friendly port/browser handling for forwarded environments
- Print the URL to the terminal for you to access
Port forwarding in VS Code devcontainers: The port should be automatically forwarded. Check the "Ports" tab.
SSH port forwarding: Add to your ~/.ssh/config:
Host your-server
LocalForward 9999 localhost:9999
Slash Commands
Plannotator's slash commands are installed as Claude Code skills in ~/.claude/skills by the install script (the canonical source is apps/skills/core/). Claude Code skills are user-invocable by directory name, so these three work like slash commands inside your session:
| Command | Description |
|---|---|
/plannotator-review [--git | --gitbutler] |
Open code review UI for current changes or a GitHub PR; optionally force the Git or GitButler provider |
/plannotator-annotate <file.md | file.html | https://... | folder/> |
Annotate a file, URL, or folder |
/plannotator-last |
Annotate the agent's last message |
Obsidian Integration
Approved plans can be automatically saved to your Obsidian vault.
Setup:
- Open Settings (gear icon) in Plannotator
- Enable "Obsidian Integration"
- Select your vault from the dropdown (auto-detected) or enter the path manually
- Set folder name (default:
plannotator)
What gets saved:
- Plans saved with human-readable filenames:
Title - Jan 2, 2026 2-30pm.md - YAML frontmatter with
created,source, andtags - Tags extracted automatically from the plan title and code languages
- Backlink to
[[Plannotator Plans]]for graph connectivity
Example saved file:
---
created: 2026-01-02T14:30:00.000Z
source: plannotator
tags: [plan, authentication, typescript, sql]
---
[[Plannotator Plans]]
# Implementation Plan: User Authentication
...