模式 1：安装

# 仅安装 CLI（macOS / Linux / WSL）
bash scripts/install.sh

# 安装 CLI 并获取 Claude Code 插件命令
bash scripts/install.sh --with-plugin

# 安装 CLI + 配置 Gemini CLI
bash scripts/install.sh --with-gemini

# 安装 CLI + 配置 Codex CLI
bash scripts/install.sh --with-codex

# 安装 CLI + 注册 OpenCode 插件
bash scripts/install.sh --with-opencode

# 安装 CLI + 一次性配置所有 AI 工具集成
bash scripts/install.sh --all

功能说明：

• 检测操作系统（macOS / Linux / WSL / Windows）
• 检查 Obsidian 是否安装，如果缺失则显示安装链接：https://obsidian.md/download
• 通过 https://plannotator.ai/install.sh 安装
• 验证安装和 PATH 环境变量
• 可选地为每个 AI 工具运行集成脚本
• 在 Windows 上：打印需要手动运行的 PowerShell / CMD 命令

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

# 将钩子添加到 ~/.claude/settings.json
bash scripts/setup-hook.sh

# 预览将进行的更改（不实际写入）
bash scripts/setup-hook.sh --dry-run

功能说明：

• 检查 plannotator CLI 是否已安装
• 安全地将 ExitPlanMode 钩子合并到 ~/.claude/settings.json 中（先备份）
• 如果钩子已配置则跳过
• 运行此脚本后请重启 Claude Code

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

在 Claude Code 中运行：

/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator
# 重要：插件安装后请重启 Claude Code

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

当 Claude Code 退出计划模式时，通过钩子自动触发。

当你的代理完成计划时（Claude Code：按 Shift+Tab×2 进入计划模式），plannotator 会自动打开：

1. 查看 代理的计划，使用可视化 UI
2. 批注 并明确意图：
   • delete — 删除有风险或不必要的步骤
   • insert — 添加缺失的步骤
   • replace — 修正错误的方法
   • comment — 阐明约束条件或验收标准
3. 提交 一个结果：
   • 批准 → 代理继续执行实现
   • 请求更改 → 你的批注将作为结构化反馈发送回去，用于重新规划

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

# 审查所有未提交的更改
bash scripts/review.sh

# 审查特定的提交
bash scripts/review.sh HEAD~1

# 审查分支差异
bash scripts/review.sh main...HEAD

功能说明：

• 检查 CLI 和 git 仓库状态
• 在打开前显示差异摘要
• 启动 plannotator review UI
• 在 UI 中：选择行号进行批注，切换统一/分屏视图，附加图片

模式 5：远程 / Devcontainer 模式

# 交互式设置（SSH、devcontainer、WSL）
bash scripts/configure-remote.sh

# 查看当前配置
bash scripts/configure-remote.sh --show

# 直接设置端口
bash scripts/configure-remote.sh --port 9999

功能说明：

• 检测 shell 配置文件（.zshrc、.bashrc、.profile）
• 将 PLANNOTATOR_REMOTE=1 和 PLANNOTATOR_PORT 写入 shell 配置文件
• 显示 SSH 和 VS Code 端口转发说明
• 可选地设置自定义浏览器或分享 URL

手动设置环境变量：

export PLANNOTATOR_REMOTE=1    # 不自动打开浏览器
export PLANNOTATOR_PORT=9999   # 用于转发的固定端口

模式 6：状态检查

bash scripts/check-status.sh

检查以下所有项目：

• CLI 是否安装及其版本
• ~/.claude/settings.json 中的 Claude Code 钩子（或检测到插件）
• ~/.gemini/settings.json 中的 Gemini CLI 钩子
• Codex CLI ~/.codex/config.toml 中的 developer_instructions
• opencode.json 中的 OpenCode 插件 + 斜杠命令
• Obsidian 安装
• 环境变量配置
• git 仓库是否可用于差异审查

模式 7：Gemini CLI 集成

# 配置 Gemini CLI（钩子 + GEMINI.md 说明）
bash scripts/setup-gemini-hook.sh

# 预览将进行的更改（不实际写入）
bash scripts/setup-gemini-hook.sh --dry-run

# 仅更新 settings.json 钩子（跳过 GEMINI.md）
bash scripts/setup-gemini-hook.sh --hook-only

# 仅更新 GEMINI.md（跳过 settings.json）
bash scripts/setup-gemini-hook.sh --md-only

功能说明：

• 检查 plannotator CLI 是否已安装
• 将 ExitPlanMode 钩子合并到 ~/.gemini/settings.json 中（格式与 Claude Code 相同）
• 将 plannotator 使用说明追加到 ~/.gemini/GEMINI.md
• 在修改前备份现有文件

设置后在 Gemini CLI 中的用法：

# 进入计划模式（退出时触发钩子）
gemini --approval-mode plan

# 手动计划审查（已验证格式）
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 &

# 实现后的代码审查
plannotator review

注意： Gemini CLI 支持 gemini hooks migrate --from-claude 来自动迁移现有的 Claude Code 钩子。

模式 8：Codex CLI 集成

# 配置 Codex CLI（developer_instructions + 提示词文件）
bash scripts/setup-codex-hook.sh

# 预览将进行的更改（不实际写入）
bash scripts/setup-codex-hook.sh --dry-run

功能说明：

• 将 plannotator 指令添加到 ~/.codex/config.toml 中的 developer_instructions
• 创建 ~/.codex/prompts/plannotator.md（使用 /prompts:plannotator 调用）
• 在修改前备份现有配置

设置后在 Codex CLI 中的用法：

# 使用 plannotator 代理提示词
/prompts:plannotator

# 手动计划审查（已验证格式）
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 &

# 实现后的代码审查
plannotator review HEAD~1

注意：使用 heredoc/echo 的 plannotator plan - 可能会失败，并显示 Failed to parse hook event from stdin。请使用上述的 python3 JSON 格式。

模式 10：通过导出 → 笔记选项卡手动保存

随时将当前计划保存到 Obsidian 或 Bear Notes — 无需批准或拒绝。

如何访问

1. 点击 plannotator UI 工具栏中的 导出 按钮
2. 点击 笔记 选项卡（不是分享或批注）
3. 你将看到：
   • Obsidian 行，显示配置的保险库路径和 保存 按钮
   • Bear 行，显示 保存 按钮
   • 全部保存 按钮，可同时保存两者
4. 每行旁边的绿点表示该集成已配置
5. 点击 保存 完成后会显示 已保存

何时使用

• 保存进行中的计划，无需做出批准/拒绝的最终决定
• 审查后快速存档，无需最终决定
• 保存已批注的计划供团队参考

要求

• plannotator 必须在 钩子模式 下运行（正常的 Claude Code ExitPlanMode 钩子调用 = 钩子模式）
• Obsidian/Bear 必须在设置（⚙️）→ 保存选项卡中配置
• 设置存储在 cookies 中（非 localStorage），并在重启后持久化

注意： 笔记选项卡使用 POST /api/save-notes，该接口直接写入保险库文件系统（Obsidian）或调用 bear://x-callback-url/create（Bear）。此端点仅在钩子模式下可用。

推荐工作流程

快速开始（所有 AI 工具）

# 1. 安装 CLI + 一次性配置所有 AI 工具集成
bash scripts/install.sh --all

# 2. 验证一切正常
bash scripts/check-status.sh

# 3. 重启你的 AI 工具（Claude Code、Gemini CLI、OpenCode、Codex）

Claude Code（手动）

1. bash scripts/install.sh --with-plugin
   └─ 安装 CLI + 显示插件安装命令

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

3. bash scripts/check-status.sh
   └─ 确认一切就绪

4. [在计划模式下使用代理编码 → Shift+Tab×2]
   └─ plannotator 自动打开

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

Gemini CLI（手动）

1. bash scripts/install.sh
2. bash scripts/setup-gemini-hook.sh
3. gemini --approval-mode plan          ← 在计划模式下工作
   └─ 退出时触发 plannotator

Codex CLI（手动）

1. bash scripts/install.sh
2. bash scripts/setup-codex-hook.sh
3. /prompts:plannotator                 ← 在 Codex 会话内部

OpenCode 设置

# 自动化设置（推荐）
bash scripts/setup-opencode-plugin.sh

# 或手动添加到 opencode.json：



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

设置后，重启 OpenCode。可用的斜杠命令：

• /plannotator-review — 为当前 git 差异打开代码审查 UI
• /plannotator-annotate <file.md> — 批注一个 markdown 文件

submit_plan 工具会自动提供给代理用于提交计划。

模式 9：Obsidian 集成设置

将批准的计划自动保存到你的 Obsidian 保险库，包含 YAML 前置元数据和标签。

前提条件

1. 安装 Obsidian：https://obsidian.md/download
2. 创建一个保险库：打开 Obsidian → 创建新保险库 → 选择位置
   • 示例：~/Documents/Obsidian/MyVault
3. 验证保险库存在：Obsidian 在首次创建保险库后会生成 obsidian.json 配置

# 检查 Obsidian 安装（macOS）

ls /Applications/Obsidian.app

# 检查 Obsidian 配置是否存在（保险库检测依赖于此）
# macOS
cat ~/Library/Application\ Support/obsidian/obsidian.json
# Linux
cat ~/.config/obsidian/obsidian.json
# Windows
cat %APPDATA%/obsidian/obsidian.json

分步设置

# 步骤 1：验证 Obsidian 已安装并至少有一个保险库
bash scripts/check-status.sh

# 步骤 2：触发一个计划审查（任何方法）
# Claude Code: Shift+Tab×2 → 计划模式 → 退出计划模式
# Gemini CLI: gemini --approval-mode plan
# OpenCode: 代理创建一个计划

# 步骤 3：在 plannotator UI 中：
#   1. 点击 ⚙️（设置齿轮图标）
#   2. 转到“保存”选项卡
#   3. 打开“Obsidian 集成”开关
#   4. 从下拉菜单中选择你的保险库（自动检测）
#      - 如果未检测到保险库，则输入自定义路径
#   5. 设置文件夹名称（默认：“plannotator”）

# 步骤 4：批准一个计划以测试集成
#   - 在 plannotator UI 中点击“批准”
#   - 检查你的保险库中是否已保存文件

Obsidian 配置选项

保存的文件格式

文件以人类可读的名称和 YAML 前置元数据保存：

文件名: {标题} - {月} {日}, {年} {时}-{分}{上午/下午}.md
示例:  User Authentication - Feb 22, 2026 10-45pm.md



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

[[Plannotator Plans]]

# 原始计划内容...

标签提取：

• plannotator — 始终包含
• 项目名称 — 来自 git 仓库或目录
• 标题词 — 来自 H1 标题的前 3 个有意义的词
• 语言 — 来自代码块（```typescript → typescript）

文件夹组织

使用子文件夹在保险库内组织计划：

vault/plannotator/
├── approved/          ← 已批准的计划
├── denied/            ← 被拒绝的计划
└── 2026-02/           ← 月度归档

手动创建子文件夹（Obsidian 会自动检测它们）：

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

或直接写入任何子文件夹：

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

Bear Notes（替代方案）

如果你更喜欢 Bear Notes 而不是 Obsidian：

1. 在设置 → 保存选项卡中打开“Bear Notes”开关
2. 计划通过 bear://x-callback-url/create 保存
3. 标签以井号标签形式追加
4. 从终端验证回调：

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

故障排除

保险库未检测到：

# 1. 检查 Obsidian 配置是否存在
ls ~/Library/Application\ Support/obsidian/obsidian.json  # macOS

# 2. 如果缺失，请打开 Obsidian 并先创建一个保险库
open /Applications/Obsidian.app

# 3. 创建保险库后，重启 plannotator

计划未保存：

# 检查保险库文件夹的写入权限
ls -la ~/path/to/vault/plannotator/

# 检查浏览器控制台是否有错误（F12 → 控制台）

导出 → 笔记选项卡的保存按钮需要钩子模式：

• 导出 → 笔记选项卡的保存按钮要求 plannotator 在 钩子模式 下运行（stdin JSON 输入）。在 CLI review/annotate 模式下，/api/save-notes 端点不活动。正常的 Claude Code 钩子调用（ExitPlanMode 钩子）始终在钩子模式下运行。

在自动化/无头浏览器中看不到设置：

• Obsidian 集成设置必须在 plannotator 自动打开的 系统浏览器 中配置。设置存储在 cookies 中（非 localStorage）。自动化/无头浏览器配置文件（Playwright、Puppeteer）使用独立的 cookie 存储，将看不到这些设置。

Bear 导出不工作：

• 确认 Bear 应用已安装并至少打开过一次
• 确认 open "bear://x-callback-url/create?..." 在终端中能工作
• 使用系统浏览器会话进行 plannotator 设置；自动化/无头会话可能会阻止自定义 URI 处理器

设置不持久化：

• 设置存储在 cookies 中（非 localStorage）
• 确保为 localhost 启用了 cookies
• 设置在不同端口间持久化

自动保存（总结）

Obsidian 集成是可选的 — 即使没有它，计划仍然可以被审查和批准。

最佳实践

1. 在代理开始编码之前使用计划审查 — 尽早发现错误的方法
2. 确保每个批注都对应一个具体、可操作的更改
3. 在“请求更改”的反馈中包含验收标准
4. 对于差异审查，批注与预期行为更改相关的精确行范围
5. 在文本不足时，使用图片批注进行 UI/UX 反馈

参考

• GitHub: backnotprop/plannotator
• 官方网站: plannotator.ai
• Obsidian 下载
• 钩子 README: apps/hook/README.md
• OpenCode 插件: apps/opencode-plugin/README.md

每周安装数

1

仓库

akillness/oh-my-gods

首次出现

1 天前

安全审计

Gen Agent Trust HubFailSocketWarnSnykFail

安装于

mcpjam1

claude-code1

replit1

junie1

windsurf1

zencoder1

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
• 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:

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

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

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

1. Click Export button in the plannotator UI toolbar
2. Click the Notes tab (not Share or Annotations)
3. You see:
   • Obsidian row with configured vault path and Save button
   • Bear row with Save button
   • Save All button to save both at once
4. A green dot next to each row means that integration is configured
5. 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

1. Install Obsidian : https://obsidian.md/download
2. Create a Vault : Open Obsidian → Create new vault → Choose location
   • Example: ~/Documents/Obsidian/MyVault
3. 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

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:

1. Toggle ON "Bear Notes" in Settings → Saving tab
2. Plans are saved via bear://x-callback-url/create
3. Tags are appended as hashtags
4. Validate callback from terminal:

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

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

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

References

• GitHub: backnotprop/plannotator
• Official site: plannotator.ai
• Obsidian download
• Hook README: apps/hook/README.md
• OpenCode plugin: apps/opencode-plugin/README.md

Weekly Installs

1

Repository

akillness/oh-my-gods

First Seen

1 day ago

Security Audits

Gen Agent Trust HubFailSocketWarnSnykFail

Installed on

mcpjam1

claude-code1

replit1

junie1

windsurf1

zencoder1