Skip to content
Back to search

open-plan-annotator

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ndom91--open-plan-annotator/badge.svg)](/listings/ndom91--open-plan-annotator)

HTML

<a href="/listings/ndom91--open-plan-annotator"><img src="/api/listings/ndom91--open-plan-annotator/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

`open-plan-annotator` is package-managed as a plugin within your harness of choice. The main plugin package then installs the specific local platform runtime it needs for your host (`linux`/`darwin`, `x86_64`/`arm64`, etc). After installing the plugin, your agent will call `open-plan-annotator` autonomously when you ask it to "make a plan" or any similar such comment, including in claude-code specifically as a hook when exiting `PlanMode`. Alternatively, you can call it yourself explicitly via the exposed command. See below for more details.

Claude Code

Install from inside Claude Code:

/plugin marketplace add ndom91/open-plan-annotator
/plugin install open-plan-annotator@ndom91-open-plan-annotator

What you get:

- `ExitPlanMode` hook: opens the annotation UI whenever Claude submits a plan - `/annotate-plan [task description]`: asks Claude to draft a plan and send it to the UI - `open-plan-annotator`: runtime command invoked by the hook

Third-party marketplace auto-update is disabled by default in Claude Code. Enable auto-update for the `ndom91-open-plan-annotator` marketplace in the Marketplace UI if you want updates automatically.

OpenCode

Add the plugin to your OpenCode V2 config (`opencode.jsonc` or `.opencode/opencode.jsonc`):

{
  "plugins": ["open-plan-annotator@latest"]
}

What you get:

- `annotate_plan`: tool the agent calls after drafting a markdown plan - `open-plan-annotator`: runtime command spawned by the plugin - optional implementation-agent handoff after approval

Restart the OpenCode background service after installing or updating so it reloads the package-managed runtime. The package default export is an OpenCode V2 plugin definition with a stable `id` and `setup()` method. It also temporarily exposes `server()` for OpenCode V1.18.29+ compatibility; the two implementations use their respective APIs.

Pi

Install the Pi extension:

pi install npm:@open-plan-annotator/pi-extension

What you get:

- `annotate_plan`: tool the agent calls after drafting a markdown plan - `/annotate-plan [plan markdown]`: command for manually reviewing supplied text or the latest assistant message - `open-plan-annotator`: runtime command used by the extension

Manual review examples:

/annotate-plan
/annotate-plan # Plan\n\n1. Do the thing

Manual / CLI

Install globally if you want to run the CLI directly:

bun add -g open-plan-annotator
npm install -g open-plan-annotator

This adds the `open-plan-annotator` command. To verify the resolved runtime:

open-plan-annotator doctor

You can also review a Markdown plan directly from disk, which is useful for agents without a native plugin:

open-plan-annotator review /absolute/path/to/plan.md

The command opens the same local review UI and blocks until approval or requested changes. It prints review result JSON to stdout when the user is done.

Generic agent setup instructions are available with:

open-plan-annotator agent-setup
open-plan-annotator help agent

Skipping the Annotator

Set `OPEN_PLAN_ANNOTATOR_SKIP_FILE` to a file path. While that file exists, the Claude Code hook exits without a decision and Claude Code shows its native plan approval instead. The file is checked on every hook call, so you can toggle it mid session, for example while continuing a session through Remote Control where the local browser UI is unreachable:

export OPEN_PLAN_ANNOTATOR_SKIP_FILE="$HOME/.open-plan-annotator-skip"
touch "$OPEN_PLAN_ANNOTATOR_SKIP_FILE"   # use native approval
rm "$OPEN_PLAN_ANNOTATOR_SKIP_FILE"      # back to the annotator

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 30 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "open-plan-annotator",
  3. "owner": {
  4. "name": "ndom91"
  5. },
  6. "metadata": {
  7. "description": "Interactive plan annotation plugin for Claude Code",
  8. "version": "1.13.2"
  9. },
  10. "plugins": [
  11. {
  12. "name": "open-plan-annotator",
  13. "source": "./",
  14. "description": "Interactive plan annotation UI: review, strikethrough, and comment on Claude's plans before approving. Fully local, no external services.",
  15. "version": "1.13.2",
  16. "author": {
  17. "name": "ndom91"
  18. },
  19. "homepage": "https://github.com/ndom91/open-plan-annotator",
  20. "license": "MIT",
  21. "keywords": [
  22. "planning",
  23. "review",
  24. "hooks",
  25. "ExitPlanMode",
  26. "annotations"
  27. ]
  28. }
  29. ]
  30. }
README.md · README · 167 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # open-plan-annotator
  2. [![npm version](https://img.shields.io/npm/v/open-plan-annotator?style=for-the-badge&labelColor=black&color=black)](https://www.npmjs.com/package/open-plan-annotator)
  3. [![License: MIT](https://img.shields.io/badge/license-MIT-orange.svg?style=for-the-badge&labelColor=black&color=black)](https://opensource.org/licenses/MIT)
  4. [![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-pink?style=for-the-badge&labelColor=black&color=black)]()
  5. A fully local agentic coding plugin that intercepts plan mode and opens an annotation UI in your browser. Mark up the plan, send structured feedback to the agent, and receive a revised version — iterate as many times as you need until you're ready to approve.
  6. Select text to <code>strikethrough</code>, <code>replace</code>, <code>insert</code>, or <code>comment</code> — then approve the plan or request changes
  7. ## How It Works
  8. 1. Your coding agent (Claude Code, OpenCode, and pi) finishes writing a plan
  9. 2. The plugin launches an ephemeral HTTP server and opens a React UI in your browser
  10. 3. You review the plan and annotate it — strikethrough, replace, insert, or comment on any section
  11. 4. **Approve** to let the agent proceed, or **Request Changes** to send your annotations back as structured feedback
  12. 5. The agent revises the plan and the cycle repeats until you're satisfied
  13. Everything runs locally.
  14. ![](.github/assets/screenshot_005.png)
  15. ## Install
  16. `open-plan-annotator` is package-managed as a plugin within your harness of choice. The main plugin package then installs the specific local platform runtime it needs for your host (`linux`/`darwin`, `x86_64`/`arm64`, etc). After installing the plugin, your agent will call `open-plan-annotator` autonomously when you ask it to "make a plan" or any similar such comment, including in claude-code specifically as a hook when exiting `PlanMode`. Alternatively, you can call it yourself explicitly via the exposed command. See below for more details.
  17. ### Claude Code
  18. Install from inside Claude Code:
  19. ```
  20. /plugin marketplace add ndom91/open-plan-annotator
  21. /plugin install open-plan-annotator@ndom91-open-plan-annotator
  22. ```
  23. What you get:
  24. - `ExitPlanMode` hook: opens the annotation UI whenever Claude submits a plan
  25. - `/annotate-plan [task description]`: asks Claude to draft a plan and send it to the UI
  26. - `open-plan-annotator`: runtime command invoked by the hook
  27. Third-party marketplace auto-update is disabled by default in Claude Code. Enable auto-update for the `ndom91-open-plan-annotator` marketplace in the Marketplace UI if you want updates automatically.
  28. ### OpenCode
  29. Add the plugin to your OpenCode V2 config (`opencode.jsonc` or `.opencode/opencode.jsonc`):
  30. ```jsonc
  31. {
  32. "plugins": ["open-plan-annotator@latest"]
  33. }
  34. ```
  35. What you get:
  36. - `annotate_plan`: tool the agent calls after drafting a markdown plan
  37. - `open-plan-annotator`: runtime command spawned by the plugin
  38. - optional implementation-agent handoff after approval
  39. Restart the OpenCode background service after installing or updating so it reloads the package-managed runtime.
  40. The package default export is an OpenCode V2 plugin definition with a stable
  41. `id` and `setup()` method. It also temporarily exposes `server()` for OpenCode
  42. V1.18.29+ compatibility; the two implementations use their respective APIs.
  43. ### Pi
  44. Install the Pi extension:
  45. ```sh
  46. pi install npm:@open-plan-annotator/pi-extension
  47. ```
  48. What you get:
  49. - `annotate_plan`: tool the agent calls after drafting a markdown plan
  50. - `/annotate-plan [plan markdown]`: command for manually reviewing supplied text or the latest assistant message
  51. - `open-plan-annotator`: runtime command used by the extension
  52. Manual review examples:
  53. ```sh
  54. /annotate-plan
  55. /annotate-plan # Plan\n\n1. Do the thing
  56. ```
  57. ### Manual / CLI
  58. Install globally if you want to run the CLI directly:
  59. ```sh
  60. bun add -g open-plan-annotator
  61. npm install -g open-plan-annotator
  62. ```
  63. This adds the `open-plan-annotator` command. To verify the resolved runtime:
  64. ```sh
  65. open-plan-annotator doctor
  66. ```
  67. You can also review a Markdown plan directly from disk, which is useful for agents without a native plugin:
  68. ```sh
  69. open-plan-annotator review /absolute/path/to/plan.md
  70. ```
  71. The command opens the same local review UI and blocks until approval or requested changes. It prints review result JSON to stdout when the user is done.
  72. Generic agent setup instructions are available with:
  73. ```sh
  74. open-plan-annotator agent-setup
  75. open-plan-annotator help agent
  76. ```
  77. ### Skipping the Annotator
  78. Set `OPEN_PLAN_ANNOTATOR_SKIP_FILE` to a file path. While that file exists, the Claude Code hook exits without a decision and Claude Code shows its native plan approval instead. The file is checked on every hook call, so you can toggle it mid session, for example while continuing a session through Remote Control where the local browser UI is unreachable:
  79. ```sh
  80. export OPEN_PLAN_ANNOTATOR_SKIP_FILE="$HOME/.open-plan-annotator-skip"
  81. touch "$OPEN_PLAN_ANNOTATOR_SKIP_FILE" # use native approval
  82. rm "$OPEN_PLAN_ANNOTATOR_SKIP_FILE" # back to the annotator
  83. ```
  84. ## Updates
  85. - **Claude Code**: navigate to the `/plugin` -> "Installed" -> `open-plan-annotator` entry and select "Update", then restart Claude Code.
  86. - **OpenCode**: bump the version number in your `opencode.jsonc` `plugins` `open-plan-annotator` entry, then restart the OpenCode service.
  87. - **Pi**: update the Pi extension, then restart Pi.
  88. - **Manual/global install**: update the npm package, then rerun `open-plan-annotator`.
  89. ## Keyboard Shortcuts
  90. | Action | Shortcut | Description |
  91. |--------|----------|-------------|
  92. | Delete | `d` | Strikethrough selected text |
  93. | Replace | `r` | Replace selected text with new content |
  94. | Insert | `s` | Insert text after the selection |
  95. | Comment | `c` | Attach a comment to selected text |
  96. | Approve | `Cmd+Enter` | Approve the plan and proceed |
  97. | Request Changes | `Cmd+Shift+Enter` | Send annotations back to the agent |
  98. ## Development
  99. ```sh
  100. bun run dev
  101. ```
  102. Starts the Bun server on port 3847 with a test plan and the Vite dev server on port 5173 with HMR.
  103. ```sh
  104. bun run lint # check
  105. bun run lint:fix # auto-fix
  106. bun run format # format
  107. ```
  108. ## Maintainer Docs
  109. - Architecture: [`docs/architecture.md`](docs/architecture.md)
  110. - Operations: [`docs/operations.md`](docs/operations.md)
  111. - Release process: [`docs/release.md`](docs/release.md)
  112. ## License
  113. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.