README

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:

# Latest release
curl -fsSL https://plannotator.ai/install.sh | bash

# Pin to a specific reviewed version
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --version vX.Y.Z

Windows PowerShell:

# Latest release
irm https://plannotator.ai/install.ps1 | iex

# Pin to a specific reviewed version
& ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Version vX.Y.Z

Windows CMD:

curl -fsSL https://plannotator.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

REM Pin to a specific reviewed version
curl -fsSL https://plannotator.ai/install.cmd -o install.cmd && install.cmd --version vX.Y.Z && del install.cmd

Released binaries ship with SHA256 sidecars and SLSA build provenance attestations from v0.17.2 onwards. See the installation docs for the supported-version matrix and 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

The plugin registers three slash commands:

Command	Description
`/plannotator-review`	Open code review UI for uncommitted changes or a GitHub PR
`/plannotator-annotate <file.md>`	Annotate any markdown file
`/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, and tags
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
...