open-plan-annotator

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.

Select text to strikethrough, replace, insert, or comment — then approve the plan or request changes

How It Works

1. Your coding agent (Claude Code or OpenCode) finishes writing a plan
2. The plugin launches an ephemeral HTTP server and opens a React UI in your browser
3. You review the plan and annotate it — strikethrough, replace, insert, or comment on any section
4. Approve to let the agent proceed, or Request Changes to send your annotations back as structured feedback
5. The agent revises the plan and the cycle repeats until you're satisfied

Everything runs locally. Nothing leaves your machine.

Install

Note

The first run might take up to 30s to pop open the UI. If your agentic coding tool installed it via pnpm, they block post-install scripts by default so Claude / OpenCode will trigger the download of the correct binary for your platform upon first use, i.e. when first transitioning out of plan mode. All subsequent runs will be instant.

Claude Code

From within Claude Code, add the marketplace and install the plugin:

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

This registers the ExitPlanMode hook that launches the annotation UI.

OpenCode

Add open-plan-annotator to the plugin array in your OpenCode config (opencode.json or .opencode/config.json):

{
  "plugin": ["open-plan-annotator"]
}

OpenCode will install the package and load it automatically. The plugin:

• Injects plan-mode instructions into the agent's system prompt
• Registers a submit_plan tool that the agent calls after creating a plan
• Spawns the annotation UI in your browser for review
• Returns structured feedback to the agent on approval or rejection
• Optionally hands off to an implementation agent after approval

Implementation Handoff

By default, after a plan is approved the plugin sends "Proceed with implementation." to a build agent. To customize or disable this, create open-plan-annotator.json in your project's .opencode/ directory or globally in ~/.config/opencode/:

{
  "implementationHandoff": {
    "enabled": true,
    "agent": "build"
  }
}

Set enabled to false to disable auto-handoff. Project config overrides global config.

Manual Install

If you want to run the binary standalone or build from source:

npm install -g open-plan-annotator

From Source

git clone https://github.com/ndom91/open-plan-annotator.git
cd open-plan-annotator
bun install
bun run build

Then load it directly in Claude Code:

claude --plugin-dir ./open-plan-annotator

Keyboard Shortcuts

Action	Shortcut	Description
Delete	d	Strikethrough selected text
Replace	r	Replace selected text with new content
Insert	i	Insert text after the selection
Comment	c	Attach a comment to selected text
Approve	Cmd+Enter	Approve the plan and proceed
Request Changes	Cmd+Shift+Enter	Send annotations back to the agent

Development

bun run dev

Starts the Bun server on port 3847 with a test plan and the Vite dev server on port 5173 with HMR.

bun run lint        # check
bun run lint:fix    # auto-fix
bun run format      # format

Maintainer Docs

• Architecture: docs/architecture.md
• Operations: docs/operations.md
• Release process: docs/release.md

License

MIT