Back to Details

plannotator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

plannotator — Interactive Plan & Diff Review (planno)

plannotator — 交互式计划与差异审查工具（planno）

Keyword: 
planno
| Source: 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 and OpenCode.
关键词: 
planno
| 来源: https://github.com/backnotprop/plannotator
以可视化方式为AI编码Agent的计划添加注释并进行审查，与团队共享，一键发送反馈。 兼容Claude Code和OpenCode。

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
  • 你希望在AI Agent开始编码前审查其实现计划
  • 你希望在Agent修改代码后为git差异添加注释
  • 你需要一个反馈循环：可视化标记需要修改的内容，然后将结构化反馈发送回去
  • 你希望通过链接与队友共享计划审查结果
  • 你希望将已批准的计划自动保存至Obsidian或Bear Notes

Scripts (Automated Patterns)

脚本（自动化模式）

All patterns have a corresponding script in 
scripts/
. Run them directly or let the agent call them.
ScriptPatternUsage
scripts/install.sh
CLI InstallOne-command install of plannotator CLI
scripts/setup-hook.sh
Hook SetupConfigure Claude Code ExitPlanMode hook
scripts/check-status.sh
Status CheckVerify full installation and configuration
scripts/configure-remote.sh
Remote ModeSSH / devcontainer / WSL configuration
scripts/review.sh
Code ReviewLaunch diff review UI
所有模式在
scripts/
目录下都有对应的脚本。可直接运行或让Agent调用它们。
脚本模式用法
scripts/install.sh
CLI安装一键安装plannotator CLI
scripts/setup-hook.sh
钩子设置配置Claude Code的ExitPlanMode钩子
scripts/check-status.sh
状态检查验证完整的安装与配置情况
scripts/configure-remote.sh
远程模式SSH / devcontainer / WSL配置
scripts/review.sh
代码审查启动差异审查UI

Pattern 1: Install

模式1：安装

bash
undefined
bash
undefined

Install CLI only (macOS / Linux / WSL)

仅安装CLI（macOS / Linux / WSL）

bash scripts/install.sh
bash scripts/install.sh

Install CLI and get Claude Code plugin commands

安装CLI并获取Claude Code插件命令

bash scripts/install.sh --with-plugin

What it does:
- Detects OS (macOS / Linux / WSL / Windows)
- Installs via `https://plannotator.ai/install.sh`
- Verifies install and PATH
- On Windows: prints PowerShell / CMD commands to run manually

---
bash scripts/install.sh --with-plugin

功能说明：
- 检测操作系统（macOS / Linux / WSL / Windows）
- 通过`https://plannotator.ai/install.sh`完成安装
- 验证安装结果与PATH配置
- 在Windows系统上：手动打印需运行的PowerShell / CMD命令

---

Pattern 2: Hook Setup (Plan Review trigger)

模式2：钩子设置（计划审查触发）

bash
undefined
bash
undefined

Add hook to ~/.claude/settings.json

将钩子添加至~/.claude/settings.json

bash scripts/setup-hook.sh
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**
bash scripts/setup-hook.sh --dry-run

功能说明：
- 检查plannotator CLI是否已安装
- 安全地将`ExitPlanMode`钩子合并至`~/.claude/settings.json`（先备份原文件）
- 若钩子已配置则跳过操作
- **运行后请重启Claude Code**

Alternative: Claude Code Plugin (no manual hook needed)

替代方案：Claude Code插件（无需手动设置钩子）

Run inside Claude Code:
bash
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator
在Claude Code中运行：
bash
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator

IMPORTANT: Restart Claude Code after plugin install

重要：安装插件后请重启Claude Code


---

---

Pattern 3: Plan Review (Before Coding)

模式3：计划审查（编码前）

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:
  1. View the agent's plan in the visual UI
  2. Annotate with clear intent: 
    • delete
      — remove risky or unnecessary step
    • insert
      — add missing step
    • replace
      — revise incorrect approach
    • comment
      — clarify constraints or acceptance criteria
  3. Submit one outcome:
    • Approve → agent proceeds with implementation
    • Request changes → your annotations are sent back as structured feedback for replanning
当Claude Code退出计划模式时，将通过钩子自动触发。
当你的Agent完成计划制定后（Claude Code：按
Shift+Tab×2
进入计划模式），plannotator将自动打开：
  1. 查看：在可视化UI中查看Agent的计划
  2. 添加注释，明确修改意图： 
    • delete
      —— 删除有风险或不必要的步骤
    • insert
      —— 添加缺失的步骤
    • replace
      —— 修改不正确的实现方案
    • comment
      —— 明确约束条件或验收标准
  3. 提交以下其中一种结果：
    • 批准 → Agent继续执行实现工作
    • 请求修改 → 你的注释将作为结构化反馈发送回Agent，以便重新制定计划

Pattern 4: Code Review (After Coding)

模式4：代码审查（编码后）

bash
undefined
bash
undefined

Review all uncommitted changes

审查所有未提交的更改

bash scripts/review.sh
bash scripts/review.sh

Review a specific commit

审查特定提交

bash scripts/review.sh HEAD~1
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

---
bash scripts/review.sh main...HEAD

功能说明：
- 检查CLI与git仓库状态
- 在打开UI前显示差异摘要
- 启动`plannotator review` UI
- 在UI中：选择行号添加注释，切换统一/拆分视图，附加图像

---

Pattern 5: Remote / Devcontainer Mode

模式5：远程 / Devcontainer模式

bash
undefined
bash
undefined

Interactive setup (SSH, devcontainer, WSL)

交互式设置（SSH, devcontainer, WSL）

bash scripts/configure-remote.sh
bash scripts/configure-remote.sh

View current configuration

查看当前配置

bash scripts/configure-remote.sh --show
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:

```bash
export PLANNOTATOR_REMOTE=1    # No auto browser open
export PLANNOTATOR_PORT=9999   # Fixed port for forwarding
VariableDescription
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
bash scripts/configure-remote.sh --port 9999

功能说明：
- 检测Shell配置文件（`.zshrc`, `.bashrc`, `.profile`）
- 将`PLANNOTATOR_REMOTE=1`和`PLANNOTATOR_PORT`写入Shell配置文件
- 显示SSH和VS Code端口转发说明
- 可选择设置自定义浏览器或共享URL

手动设置环境变量：

```bash
export PLANNOTATOR_REMOTE=1    # 不自动打开浏览器
export PLANNOTATOR_PORT=9999   # 用于转发的固定端口
变量说明
PLANNOTATOR_REMOTE
远程模式（不自动打开浏览器）
PLANNOTATOR_PORT
本地/转发的固定端口
PLANNOTATOR_BROWSER
自定义浏览器路径/应用
PLANNOTATOR_SHARE_URL
自定义共享门户URL

Pattern 6: Status Check

模式6：状态检查

bash
bash scripts/check-status.sh
Checks all of:
  • CLI installed and version
  • Hook in 
    ~/.claude/settings.json
    (or plugin detected)
  • Environment variables configured
  • Git repo available for diff review
bash
bash scripts/check-status.sh
检查以下所有内容：
  • CLI是否已安装及版本信息
  • ~/.claude/settings.json
    中的钩子（或是否检测到插件）
  • 环境变量配置情况
  • 是否有可用的git仓库用于差异审查

Recommended Workflow

推荐工作流

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]
   └─ plannotator opens automatically on Shift+Tab×2

5. bash scripts/review.sh              ← after agent finishes coding
   └─ Opens visual diff review
1. bash scripts/install.sh --with-plugin
   └─ 安装CLI + 显示插件安装命令

2. bash scripts/setup-hook.sh          ← 使用插件时可跳过此步骤
   └─ 配置自动计划审查触发器

3. bash scripts/check-status.sh
   └─ 确认所有配置已就绪

4. [在计划模式下与Agent协作编码]
   └─ 按Shift+Tab×2时，plannotator将自动打开

5. bash scripts/review.sh              ← Agent完成编码后运行
   └─ 打开可视化差异审查UI

OpenCode Setup

OpenCode设置

Add to 
opencode.json
:
json
{
  "plugin": ["@plannotator/opencode@latest"]
}
Then run the install script and restart OpenCode.
添加至
opencode.json
：
json
{
  "plugin": ["@plannotator/opencode@latest"]
}
然后运行安装脚本并重启OpenCode。

Auto-save (Obsidian / Bear Notes)

自动保存（Obsidian / Bear Notes）

  • Open Settings (gear icon) in plannotator UI
  • Enable "Obsidian Integration" and select your vault
  • Approved plans auto-save with YAML frontmatter and tags
  • 在plannotator UI中打开设置（齿轮图标）
  • 启用“Obsidian集成”并选择你的资源库
  • 已批准的计划将自动保存并附带YAML前置元数据和标签

Best Practices

最佳实践

  1. Use plan review BEFORE the agent starts coding — catch wrong approaches early
  2. Keep each annotation tied to one concrete, actionable change
  3. Include acceptance criteria in "request changes" feedback
  4. For diff review, annotate exact line ranges tied to expected behavior changes
  5. Use image annotation for UI/UX feedback where text is insufficient
  1. 在Agent开始编码前使用计划审查——尽早发现错误的实现方案
  2. 每条注释对应一个具体、可执行的修改内容
  3. 在“请求修改”的反馈中包含验收标准
  4. 进行差异审查时，为与预期行为变更相关的精确行范围添加注释
  5. 当文本不足以表达时，使用图像注释进行UI/UX反馈

References

参考资料