https://github.com/ndom91/open-plan-annotator
Agent Plan Annotator
https://github.com/ndom91/open-plan-annotator
agentic-ai claude-code-plugin opencode-plugin plan-mode
Last synced: about 1 month ago
JSON representation
Agent Plan Annotator
- Host: GitHub
- URL: https://github.com/ndom91/open-plan-annotator
- Owner: ndom91
- Created: 2026-02-24T15:31:43.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-02-28T01:32:17.000Z (about 1 month ago)
- Last Synced: 2026-03-01T05:47:25.909Z (about 1 month ago)
- Topics: agentic-ai, claude-code-plugin, opencode-plugin, plan-mode
- Language: TypeScript
- Homepage:
- Size: 3.42 MB
- Stars: 9
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# open-plan-annotator
[](https://www.npmjs.com/package/open-plan-annotator)
[](https://opensource.org/licenses/MIT)
[]()
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
### 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`):
```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/`:
```json
{
"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:
```sh
npm install -g open-plan-annotator
```
> [!NOTE]
> The first run might take a few seconds if you use pnpm, as it blocks postinstall scripts.
> Claude / OpenCode will trigger the download upon first use then.
#### From Source
```sh
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:
```sh
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
```sh
bun run dev
```
Starts the Bun server on port 3847 with a test plan and the Vite dev server on port 5173 with HMR.
```sh
bun run lint # check
bun run lint:fix # auto-fix
bun run format # format
```
## Maintainer Docs
- Architecture: [`docs/architecture.md`](docs/architecture.md)
- Operations: [`docs/operations.md`](docs/operations.md)
- Release process: [`docs/release.md`](docs/release.md)
## License
MIT