---
id: sm-plannotator
name: "plannotator"
url: https://skills.yangsir.net/skill/sm-plannotator
author: supercent-io
domain: ai-project-management-collaboration
tags: ["planning-tools", "annotation", "product-management", "collaboration-tools", "task-management"]
install_count: 10400
rating: 4.50 (417 reviews)
github: https://github.com/supercent-io/skills-template
---

# plannotator

> 此技能提供交互式计划与差异审查功能，用于可视化地标注和审查AI编码代理的计划，并可与团队成员共享。

**Stats**: 10,400 installs · 4.5/5 (417 reviews)

## Before / After 对比

### AI编码计划可视化审查，团队协作更高效

## Readme

# plannotator

# plannotator — Interactive Plan & Diff Review

Keyword: `plan` | Source: [https://github.com/backnotprop/plannotator](https://github.com/backnotprop/plannotator)

Annotate and review AI coding agent plans visually, share with your team, send feedback with one click.
Works with **Claude Code**, **OpenCode**, **Gemini CLI**, and **Codex CLI**.

## When to use this skill

- You want to review an AI agent's implementation plan BEFORE it starts coding

- You want to annotate a git diff after the agent makes changes

- You need a feedback loop: visually mark up what to change, then send structured feedback back

- You want to share plan reviews with teammates via a link

- You want to auto-save approved plans to Obsidian or Bear Notes

## Scripts (Automated Patterns)

All patterns have a corresponding script in `scripts/`. Run them directly or let the agent call them.

Script
Pattern
Usage

`scripts/install.sh`
CLI Install
One-command install; `--all` sets up every AI tool

`scripts/setup-hook.sh`
Claude Code Hook
Configure Claude Code ExitPlanMode hook

`scripts/setup-gemini-hook.sh`
Gemini CLI Hook
Configure Gemini CLI ExitPlanMode hook + GEMINI.md

`scripts/setup-codex-hook.sh`
Codex CLI Setup
Configure Codex CLI developer_instructions + prompt

`scripts/setup-opencode-plugin.sh`
OpenCode Plugin
Register plugin + slash commands

`scripts/check-status.sh`
Status Check
Verify all integrations and configuration

`scripts/configure-remote.sh`
Remote Mode
SSH / devcontainer / WSL configuration

`scripts/review.sh`
Code Review
Launch diff review UI

## Pattern 1: Install

```
# Install CLI only (macOS / Linux / WSL)
bash scripts/install.sh

# Install CLI and get Claude Code plugin commands
bash scripts/install.sh --with-plugin

# Install CLI + configure Gemini CLI
bash scripts/install.sh --with-gemini

# Install CLI + configure Codex CLI
bash scripts/install.sh --with-codex

# Install CLI + register OpenCode plugin
bash scripts/install.sh --with-opencode

# Install CLI + all AI tool integrations at once
bash scripts/install.sh --all

```

What it does:

- Detects OS (macOS / Linux / WSL / Windows)

- Checks for Obsidian and shows install link if missing: [https://obsidian.md/download](https://obsidian.md/download)

- Installs via `https://plannotator.ai/install.sh`

- Verifies install and PATH

- Optionally runs integration scripts for each AI tool

- On Windows: prints PowerShell / CMD commands to run manually

## Pattern 2: Hook Setup (Plan Review trigger)

```
# Add hook to ~/.claude/settings.json
bash scripts/setup-hook.sh

# Preview what would change (no writes)
bash scripts/setup-hook.sh --dry-run

```

What it does:

- Checks plannotator CLI is installed

- Merges `ExitPlanMode` hook into `~/.claude/settings.json` safely (backs up first)

- Skips if hook already configured

- **Restart Claude Code after running this**

### Alternative: Claude Code Plugin (no manual hook needed)

Run inside Claude Code:

```
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator
# IMPORTANT: Restart Claude Code after plugin install

```

## Pattern 3: Plan Review (Before Coding)

Triggered automatically via hook when Claude Code exits plan mode.

When your agent finishes planning (Claude Code: `Shift+Tab×2` to enter plan mode), plannotator opens automatically:

- **View** the agent's plan in the visual UI

- **Annotate** with clear intent:

`delete` — remove risky or unnecessary step

- `insert` — add missing step

- `replace` — revise incorrect approach

- `comment` — clarify constraints or acceptance criteria

- **Submit** one outcome:

**Approve** → agent proceeds with implementation

- **Request changes** → your annotations are sent back as structured feedback for replanning

## Pattern 4: Code Review (After Coding)

```
# Review all uncommitted changes
bash scripts/review.sh

# Review a specific commit
bash scripts/review.sh HEAD~1

# Review branch diff
bash scripts/review.sh main...HEAD

```

What it does:

- Checks CLI and git repo state

- Shows diff summary before opening

- Launches `plannotator review` UI

- In the UI: select line numbers to annotate, switch unified/split views, attach images

## Pattern 5: Remote / Devcontainer Mode

```
# Interactive setup (SSH, devcontainer, WSL)
bash scripts/configure-remote.sh

# View current configuration
bash scripts/configure-remote.sh --show

# Set port directly
bash scripts/configure-remote.sh --port 9999

```

What it does:

- Detects shell profile (`.zshrc`, `.bashrc`, `.profile`)

- Writes `PLANNOTATOR_REMOTE=1` and `PLANNOTATOR_PORT` to shell profile

- Shows SSH and VS Code port-forwarding instructions

- Optionally sets custom browser or share URL

Manual environment variables:

```
export PLANNOTATOR_REMOTE=1    # No auto browser open
export PLANNOTATOR_PORT=9999   # Fixed port for forwarding

```

Variable
Description

`PLANNOTATOR_REMOTE`
Remote mode (no auto browser open)

`PLANNOTATOR_PORT`
Fixed local/forwarded port

`PLANNOTATOR_BROWSER`
Custom browser path/app

`PLANNOTATOR_SHARE_URL`
Custom share portal URL

## Pattern 6: Status Check

```
bash scripts/check-status.sh

```

Checks all of:

- CLI installed and version

- Claude Code hook in `~/.claude/settings.json` (or plugin detected)

- Gemini CLI hook in `~/.gemini/settings.json`

- Codex CLI `~/.codex/config.toml` developer_instructions

- OpenCode plugin in `opencode.json` + slash commands

- Obsidian installation

- Environment variables configured

- Git repo available for diff review

## Pattern 7: Gemini CLI Integration

```
# Configure Gemini CLI (hook + GEMINI.md instructions)
bash scripts/setup-gemini-hook.sh

# Preview what would change (no writes)
bash scripts/setup-gemini-hook.sh --dry-run

# Only update settings.json hook (skip GEMINI.md)
bash scripts/setup-gemini-hook.sh --hook-only

# Only update GEMINI.md (skip settings.json)
bash scripts/setup-gemini-hook.sh --md-only

```

What it does:

- Checks plannotator CLI is installed

- Merges `ExitPlanMode` hook into `~/.gemini/settings.json` (same format as Claude Code)

- Appends plannotator usage instructions to `~/.gemini/GEMINI.md`

- Backs up existing files before modifying

Usage in Gemini CLI after setup:

```
# Enter planning mode (hook fires when you exit)
gemini --approval-mode plan

# Manual plan review (validated format)
python3 -c "
import json
plan = open('plan.md').read()
print(json.dumps({'tool_input': {'plan': plan, 'permission_mode': 'acceptEdits'}}))
" | plannotator > /tmp/plannotator_feedback.txt 2>&1 &

# Code review after implementation
plannotator review

```

**Note:** Gemini CLI supports `gemini hooks migrate --from-claude` to auto-migrate existing Claude Code hooks.

## Pattern 8: Codex CLI Integration

```
# Configure Codex CLI (developer_instructions + prompt file)
bash scripts/setup-codex-hook.sh

# Preview what would change (no writes)
bash scripts/setup-codex-hook.sh --dry-run

```

What it does:

- Adds plannotator instruction to `developer_instructions` in `~/.codex/config.toml`

- Creates `~/.codex/prompts/plannotator.md` (invoke with `/prompts:plannotator`)

- Backs up existing config before modifying

Usage in Codex CLI after setup:

```
# Use the plannotator agent prompt
/prompts:plannotator

# Manual plan review (validated format)
python3 -c "
import json
plan = open('plan.md').read()
print(json.dumps({'tool_input': {'plan': plan, 'permission_mode': 'acceptEdits'}}))
" | plannotator > /tmp/plannotator_feedback.txt 2>&1 &

# Code review after implementation
plannotator review HEAD~1

```

Note: `plannotator plan -` with heredoc/echo can fail with `Failed to parse hook event from stdin`. Use the python3 JSON format above.

## Pattern 10: Manual Save via Export → Notes Tab

Save the current plan to Obsidian or Bear Notes at any time — without approving or denying.

### How to access

- Click **Export** button in the plannotator UI toolbar

- Click the **Notes** tab (not Share or Annotations)

- You see:

**Obsidian** row with configured vault path and **Save** button

- **Bear** row with **Save** button

- **Save All** button to save both at once

- A green dot next to each row means that integration is configured

- Clicking **Save** shows **Saved** when complete

### When to use

- Save work-in-progress plans without committing to Approve/Deny

- Quick archive after reviewing without final decision

- Save annotated plans for team reference

### Requirements

- plannotator must be running in **hook mode** (normal Claude Code ExitPlanMode hook invocation = hook mode)

- Obsidian/Bear must be configured in Settings (⚙️) → Saving tab

- Settings are stored in **cookies** (not localStorage) and persist across restarts

**Note:** The Notes tab uses `POST /api/save-notes` which writes directly to the vault filesystem (Obsidian) or calls `bear://x-callback-url/create` (Bear). This endpoint is only available in hook mode.

## Recommended Workflow

### Quick Start (all AI tools)

```
# 1. Install CLI + configure all AI tool integrations at once
bash scripts/install.sh --all

# 2. Verify everything
bash scripts/check-status.sh

# 3. Restart your AI tools (Claude Code, Gemini CLI, OpenCode, Codex)

```

### Claude Code (manual)

```
1. bash scripts/install.sh --with-plugin
   └─ Installs CLI + shows plugin install commands

2. bash scripts/setup-hook.sh          ← skip if using plugin
   └─ Configures automatic plan review trigger

3. bash scripts/check-status.sh
   └─ Confirm everything is ready

4. [Code with agent in plan mode → Shift+Tab×2]
   └─ plannotator opens automatically

5. bash scripts/review.sh              ← after agent finishes coding
   └─ Opens visual diff review

```

### Gemini CLI (manual)

```
1. bash scripts/install.sh
2. bash scripts/setup-gemini-hook.sh
3. gemini --approval-mode plan          ← work in plan mode
   └─ plannotator fires on exit

```

### Codex CLI (manual)

```
1. bash scripts/install.sh
2. bash scripts/setup-codex-hook.sh
3. /prompts:plannotator                 ← inside Codex session

```

## OpenCode Setup

```
# Automated (recommended)
bash scripts/setup-opencode-plugin.sh

# Or add manually to opencode.json:

```

```
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@plannotator/opencode@latest"]
}

```

After setup, restart OpenCode. Available slash commands:

- `/plannotator-review` — open code review UI for current git diff

- `/plannotator-annotate <file.md>` — annotate a markdown file

The `submit_plan` tool is automatically available to the agent for plan submission.

## Pattern 9: Obsidian Integration Setup

Auto-save approved plans to your Obsidian vault with YAML frontmatter and tags.

### Prerequisites

- **Install Obsidian**: [https://obsidian.md/download](https://obsidian.md/download)

- **Create a Vault**: Open Obsidian → Create new vault → Choose location

Example: `~/Documents/Obsidian/MyVault`

- **Verify Vault Exists**: Obsidian creates `obsidian.json` config after first vault creation

```
# Check Obsidian installation (macOS)
ls /Applications/Obsidian.app

# Check Obsidian config exists (vault detection depends on this)
# macOS
cat ~/Library/Application\ Support/obsidian/obsidian.json
# Linux
cat ~/.config/obsidian/obsidian.json
# Windows
cat %APPDATA%/obsidian/obsidian.json

```

### Step-by-Step Setup

```
# Step 1: Verify Obsidian is installed and has at least one vault
bash scripts/check-status.sh

# Step 2: Trigger a plan review (any method)
# Claude Code: Shift+Tab×2 → plan mode → exit plan mode
# Gemini CLI: gemini --approval-mode plan
# OpenCode: Agent creates a plan

# Step 3: In the plannotator UI:
#   1. Click ⚙️ (Settings gear icon)
#   2. Go to "Saving" tab
#   3. Toggle ON "Obsidian Integration"
#   4. Select your vault from dropdown (auto-detected)
#      - Or enter custom path if vault not detected
#   5. Set folder name (default: "plannotator")

# Step 4: Approve a plan to test the integration
#   - Click "Approve" in the plannotator UI
#   - Check your vault for the saved file

```

### Obsidian Configuration Options

Setting
Description
Default

**Vault**
Path to Obsidian vault
Auto-detected

**Folder**
Subfolder in vault for plans
`plannotator`

**Custom Path**
Manual path if auto-detect fails
-

### Saved File Format

Files are saved with human-readable names and YAML frontmatter:

```
Filename: {Title} - {Month} {Day}, {Year} {Hour}-{Minute}{am/pm}.md
Example:  User Authentication - Feb 22, 2026 10-45pm.md

```

```
---
created: 2026-02-22T22:45:30.000Z
source: plannotator
tags: [plannotator, project-name, typescript, ...]
---

[[Plannotator Plans]]

# Original plan content...

```

**Tag extraction:**

- `plannotator` — always included

- Project name — from git repo or directory

- Title words — first 3 meaningful words from H1 heading

- Languages — from code blocks (```typescript → typescript)

### Folder Organization

Organize plans within the vault using subfolders:

```
vault/plannotator/
├── approved/          ← approved plans
├── denied/            ← rejected plans
└── 2026-02/           ← monthly archive

```

Create subfolders manually (Obsidian detects them automatically):

```
mkdir -p ~/path/to/vault/plannotator/approved
mkdir -p ~/path/to/vault/plannotator/denied
mkdir -p ~/path/to/vault/plannotator/2026-02

```

Or write directly to any subfolder:

```
cp ~/.plannotator/plans/<name>-approved.md ~/path/to/vault/plannotator/approved/

```

### Bear Notes (Alternative)

If you prefer Bear Notes over Obsidian:

- Toggle ON "Bear Notes" in Settings → Saving tab

- Plans are saved via `bear://x-callback-url/create`

- Tags are appended as hashtags

- Validate callback from terminal:

```
open "bear://x-callback-url/create?title=Plannotator%20Check&text=Bear%20callback%20OK"

```

Feature
Obsidian
Bear

Storage
File system
x-callback-url

Frontmatter
YAML
None (hashtags)

Platforms
macOS/Win/Linux
macOS/iOS

### Troubleshooting

**Vault not detected:**

```
# 1. Check Obsidian config exists
ls ~/Library/Application\ Support/obsidian/obsidian.json  # macOS

# 2. If missing, open Obsidian and create a vault first
open /Applications/Obsidian.app

# 3. After creating vault, restart plannotator

```

**Plans not saving:**

```
# Check write permissions on vault folder
ls -la ~/path/to/vault/plannotator/

# Check browser console for errors (F12 → Console)

```

**Export → Notes tab Save buttons require hook mode:**

- Export → Notes tab Save buttons require plannotator running in **hook mode** (stdin JSON input). In CLI `review`/`annotate` modes, the `/api/save-notes` endpoint is not active. Normal Claude Code hook invocation (ExitPlanMode hook) always runs in hook mode.

**Settings not visible in automated/headless browsers:**

- Obsidian Integration settings must be configured in the **system browser** that plannotator auto-opens. Settings are stored in cookies (not localStorage). Automated/headless browser profiles (Playwright, Puppeteer) use isolated cookie jars and will not see these settings.

**Bear export not working:**

- Confirm Bear app is installed and opened at least once

- Confirm `open "bear://x-callback-url/create?..."` works from terminal

- Use system browser session for plannotator settings; automated/headless sessions can block custom URI handlers

**Settings not persisting:**

- Settings are stored in cookies (not localStorage)

- Ensure cookies are enabled for localhost

- Settings persist across different ports

## Auto-save (Summary)

Obsidian integration is **optional** — plans can still be reviewed and approved without it.

## Best Practices

- Use plan review BEFORE the agent starts coding — catch wrong approaches early

- Keep each annotation tied to one concrete, actionable change

- Include acceptance criteria in "request changes" feedback

- For diff review, annotate exact line ranges tied to expected behavior changes

- Use image annotation for UI/UX feedback where text is insufficient

## References

- [GitHub: backnotprop/plannotator](https://github.com/backnotprop/plannotator)

- [Official site: plannotator.ai](https://plannotator.ai)

- [Obsidian download](https://obsidian.md/download)

- [Hook README: apps/hook/README.md](https://github.com/backnotprop/plannotator/blob/main/apps/hook/README.md)

- [OpenCode plugin: apps/opencode-plugin/README.md](https://github.com/backnotprop/plannotator/blob/main/apps/opencode-plugin/README.md)

Weekly Installs10.3KRepository[supercent-io/sk…template](https://github.com/supercent-io/skills-template)GitHub Stars58First SeenFeb 20, 2026Security Audits[Gen Agent Trust HubFail](/supercent-io/skills-template/plannotator/security/agent-trust-hub)[SocketWarn](/supercent-io/skills-template/plannotator/security/socket)[SnykFail](/supercent-io/skills-template/plannotator/security/snyk)Installed oncodex10.2Kgemini-cli10.2Kopencode10.2Kkimi-cli10.2Kgithub-copilot10.2Kamp10.2K

---
*Source: https://skills.yangsir.net/skill/sm-plannotator*
*Markdown mirror: https://skills.yangsir.net/api/skill/sm-plannotator/markdown*