{"_id":"@aoligiegie/plannotator-opencode","name":"@aoligiegie/plannotator-opencode","dist-tags":{"latest":"0.27.6"},"versions":{"0.27.6":{"name":"@aoligiegie/plannotator-opencode","version":"0.27.6","type":"module","description":"Plannotator plugin for OpenCode - interactive plan review with visual annotation","author":{"name":"backnotprop"},"license":"MIT OR Apache-2.0","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/eightHundreds/plannotator.git","directory":"apps/opencode-plugin"},"homepage":"https://github.com/eightHundreds/plannotator","bugs":{"url":"https://github.com/eightHundreds/plannotator/issues"},"keywords":["opencode","opencode-plugin","plannotator","plan-review","ai-agent","coding-agent"],"//":"OpenCode 1 loads main, while OpenCode 2 loads exports[.]. Do not add ./server: OpenCode 1 checks it before main and would load the V2 adapter.","main":"dist/index.js","exports":{".":"./dist/server.js"},"//files":"skills/ is generated by build:skill from apps/skills/core/plannotator and is gitignored, so the shipped copy cannot drift from the single source.","scripts":{"build":"bun run build:skill && mkdir -p dist && cp ../hook/dist/index.html ./plannotator.html && cp ../review/dist/index.html ./review-editor.html && bun build embedded.ts --outfile dist/embedded.js --target bun --external @opencode-ai/plugin && bun build index.ts --outfile dist/index.js --target node && bun build server.ts --outfile dist/server.js --target node --external @opencode-ai/plugin","build:skill":"rm -rf skills && mkdir -p skills && cp -R ../skills/core/plannotator skills/plannotator","smoke:v2":"bun fixtures/v2-installed-smoke.ts","postinstall":"mkdir -p ${XDG_CONFIG_HOME:-$HOME/.config}/opencode/commands && cp ./commands/*.md ${XDG_CONFIG_HOME:-$HOME/.config}/opencode/commands/ 2>/dev/null || true; mkdir -p ${XDG_CONFIG_HOME:-$HOME/.config}/opencode/skills/plannotator && cp ./skills/plannotator/SKILL.md ${XDG_CONFIG_HOME:-$HOME/.config}/opencode/skills/plannotator/ 2>/dev/null || true","prepublishOnly":"bun run build"},"devDependencies":{"@opencode-ai/plugin":"0.0.0-next-16775","@plannotator/server":"workspace:*","@plannotator/shared":"workspace:*"},"engines":{"bun":">=1.0.0"},"gitHead":"fecb2830460345f9284183e5b0b414d8fbcf1fcc","_id":"@aoligiegie/plannotator-opencode@0.27.6","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-taum/nSOnJkKfbaTBa45wx5AEo27hCZRb9IRBNWaO1sPI1OOb2yg1BpwsjrmA+qNrUWBUFMvES1XMisMps7Lvw==","shasum":"1b7232c18923051b873d35bacc7af950976dfe79","tarball":"https://registry.npmjs.org/@aoligiegie/plannotator-opencode/-/plannotator-opencode-0.27.6.tgz","fileCount":12,"unpackedSize":53606230,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDPyDeqLuq3bme8gpBfAZBqFcT/C1n5jeqN7W6zHTzQfAiBi9xlftTbt0+bHwiHka45txn2x1k9NbVybrpAMDRo35A=="}]},"_npmUser":{"name":"aoligiegie","email":"mingoing@outlook.com"},"directories":{},"maintainers":[{"name":"aoligiegie","email":"mingoing@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/plannotator-opencode_0.27.6_1787534960482_0.2506883229149721"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-24T01:29:20.345Z","0.27.6":"2026-08-24T01:29:20.821Z","modified":"2026-08-24T01:29:21.005Z"},"maintainers":[{"name":"aoligiegie","email":"mingoing@outlook.com"}],"description":"Plannotator plugin for OpenCode - interactive plan review with visual annotation","homepage":"https://github.com/eightHundreds/plannotator","keywords":["opencode","opencode-plugin","plannotator","plan-review","ai-agent","coding-agent"],"repository":{"type":"git","url":"git+https://github.com/eightHundreds/plannotator.git","directory":"apps/opencode-plugin"},"author":{"name":"backnotprop"},"bugs":{"url":"https://github.com/eightHundreds/plannotator/issues"},"license":"MIT OR Apache-2.0","readme":"# @plannotator/opencode\n\n**Annotate plans. Not in the terminal.**\n\nInteractive Plan Review for OpenCode. Select the exact parts of the plan you want to change—mark for deletion, add a comment, or suggest a replacement. Feedback flows back to your agent automatically.\n\nObsidian users can auto-save approved plans to Obsidian as well. [See details](#obsidian-integration)\n\n
\n\n## Install\n\n### OpenCode 2 beta\n\nInstall OpenCode 2 from npm's `next` tag, then add Plannotator to the V2 `plugins` field:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"plugins\": [\n {\n \"package\": \"@plannotator/opencode@latest\",\n \"options\": {\n \"workflow\": \"plan-agent\",\n \"planningAgents\": [\"plan\"]\n }\n }\n ]\n}\n```\n\nRestart OpenCode 2 and verify that `plannotator` appears in `opencode2 plugin list`.\n\nOpenCode 2 support is experimental while its plugin API is in beta. The core `submit_plan` review flow works, but the current API has these limitations:\n\n- OpenCode 2 does not expose a native slash-command execution hook. Its command definitions expand to model prompts, so `/plannotator-review`, `/plannotator-annotate`, and `/plannotator-last` remain OpenCode 1-only instead of silently becoming model-mediated commands.\n- V2 tool execution does not expose an abort signal. Cancelling a turn cannot yet stop a running review server or CLI child immediately.\n- The V2 plugin context cannot switch the active session agent. Agent switching selected in the review UI is ignored with a server-log warning; switch to `build` manually after approval before implementation.\n- The V2 plugin context has no TUI toast/log API, so remote session URLs are written to the server output rather than shown as a toast.\n\n### OpenCode 1\n\nAdd to your `opencode.json`:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"plugin\": [\"@plannotator/opencode@latest\"]\n}\n```\n\nRestart OpenCode. By default, the `submit_plan` tool is available to OpenCode's `plan` agent, not to `build` or other primary agents.\n\n> **OpenCode 1 slash commands:** Run the install script to get `/plannotator-review`, `/plannotator-annotate`, and `/plannotator-last`:\n> ```bash\n> curl -fsSL https://plannotator.ai/install.sh | bash\n> ```\n> This also clears any cached plugin versions.\n\n## Workflow Modes\n\nThe examples below use the OpenCode 1 config shape. OpenCode 2 places the same option keys under the plugin entry's `options` object shown above. In V2, `manual` intentionally registers no tool and native slash-command handlers are unavailable, so it currently leaves the integration inactive.\n\n- **`plan-agent`** (default): `submit_plan` is available to OpenCode's built-in `plan` agent plus any extra agents listed in `planningAgents`. This keeps Plannotator integrated with OpenCode plan mode without nudging `build` to call it.\n- **`manual`**: `submit_plan` is not registered. Use `/plannotator-last`, `/plannotator-annotate`, and `/plannotator-review` when you want Plannotator.\n- **`user-managed`**: `submit_plan` is registered but no prompts or agent permissions are modified. You manage which agents can call `submit_plan` via OpenCode's native agent configuration.\n- **`all-agents`**: legacy broad behavior. Primary agents can see and call `submit_plan`.\n\nDefault config:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"plugin\": [\n [\"@plannotator/opencode@latest\", {\n \"workflow\": \"plan-agent\",\n \"planningAgents\": [\"plan\"]\n }]\n ]\n}\n```\n\nRuntime selection is automatic. In Bun-hosted OpenCode, Plannotator uses the embedded server bundled with the plugin. In Node-hosted or wrapped OpenCode environments, the plugin falls back to the installed `plannotator` CLI and sends the result back through OpenCode. You can force the fallback while debugging:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"plugin\": [\n [\"@plannotator/opencode@latest\", {\n \"runtime\": \"cli\"\n }]\n ]\n}\n```\n\nIf you use other OpenCode plugins, keep everything in one `plugin` array and attach Plannotator's options directly to the Plannotator entry:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"plugin\": [\n [\"@plannotator/opencode@latest\", {\n \"workflow\": \"plan-agent\",\n \"planningAgents\": [\"plan\", \"sisyphus\"]\n }],\n \"@tarquinen/opencode-dcp@latest\",\n \"octto\",\n \"oh-my-opencode-slim\"\n ]\n}\n```\n\nDo not put `{ \"workflow\": \"plan-agent\" }` as its own item in the `plugin` array. OpenCode plugin entries must be either a plugin string or a two-item array like `[pluginName, options]`.\n\nRestore the old broad behavior:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"plugin\": [\n [\"@plannotator/opencode@latest\", {\n \"workflow\": \"all-agents\"\n }]\n ]\n}\n```\n\nUse commands only:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"plugin\": [\n [\"@plannotator/opencode@latest\", {\n \"workflow\": \"manual\"\n }]\n ]\n}\n```\n\nRegister the tool but manage prompts and permissions yourself:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"plugin\": [\n [\"@plannotator/opencode@latest\", {\n \"workflow\": \"user-managed\"\n }]\n ]\n}\n```\n\n## How It Works\n\n1. The configured planning agent calls `submit_plan` → Plannotator opens in your browser\n2. Select text → annotate (delete, replace, comment)\n3. **Approve** → Agent proceeds with implementation\n4. **Request changes** → Annotations sent back as structured feedback\n\n## Features\n\n- **Visual annotations**: Select text, choose an action, see feedback in the sidebar\n- **Local by default**: Plans, annotations, drafts, history, and configuration stay local. Every app load checks GitHub for updates without sending plan content, and there is currently no opt-out setting; URL annotation, hosted PR review, AI, sharing, and Workspaces use the network when selected.\n- **Legacy link sharing**: Small markdown shares use compressed, unencrypted URL fragments. Larger and raw HTML shares can use client-encrypted short links. Workspaces is the primary direction for team sharing.\n- **Plan Diff**: See what changed when the agent revises a plan after feedback\n- **Annotate last message**: Run `/plannotator-last` to annotate the agent's most recent response\n- **Annotate files, folders, and URLs**: Run `/plannotator-annotate` when you want manual review of an artifact\n- **Obsidian integration**: Auto-save approved plans to your vault with frontmatter and tags\n\n## Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `PLANNOTATOR_REMOTE` | Set to `1` / `true` for remote mode, `0` / `false` for local mode, or leave unset for SSH auto-detection. Uses a fixed port in remote mode; browser-opening behavior depends on the environment. |\n| `PLANNOTATOR_PORT` | Fixed port to use. Default: random locally, `19432` for remote sessions. |\n| `PLANNOTATOR_BROWSER` | Custom browser to open plans in. macOS: app name or path. Linux/Windows: executable path. |\n| `PLANNOTATOR_SHARE_URL` | Custom share portal URL for self-hosting. Default: `https://share.plannotator.ai`. |\n| `PLANNOTATOR_PASTE_URL` | Custom paste service URL for self-hosting. Default: `https://plannotator-paste.plannotator.workers.dev`. |\n| `PLANNOTATOR_PLAN_TIMEOUT_SECONDS` | Timeout for `submit_plan` review wait. Default: `345600` (96h). Set `0` to disable timeout. |\n| `PLANNOTATOR_BIN` | Override the CLI path used by the OpenCode plugin's CLI runtime fallback. Default: `plannotator` on `PATH`. |\n\n## Devcontainer / Docker\n\nWorks in containerized environments. Set the env vars and forward the port:\n\n```json\n{\n \"containerEnv\": {\n \"PLANNOTATOR_REMOTE\": \"1\",\n \"PLANNOTATOR_PORT\": \"9999\"\n },\n \"forwardPorts\": [9999]\n}\n```\n\nIf nothing opens automatically, open `http://localhost:9999` when `submit_plan` is called.\n\nSee [devcontainer.md](./devcontainer.md) for full setup details.\n\n## Obsidian Integration\n\nSave approved plans directly to your Obsidian vault.\n\n1. Open Settings in Plannotator UI\n2. Enable \"Obsidian Integration\" and select your vault\n3. Approved plans save automatically with:\n - Human-readable filenames: `Title - Jan 2, 2026 2-30pm.md`\n - YAML frontmatter (`created`, `source`, `tags`)\n - Auto-extracted tags from plan title and code languages\n - Backlink to `[[Plannotator Plans]]` for graph view\n \n\n\n\n## Links\n\n- [Website](https://plannotator.ai)\n- [GitHub](https://github.com/backnotprop/plannotator)\n- [Claude Code Plugin](https://github.com/backnotprop/plannotator/tree/main/apps/hook)\n\n## License\n\nCopyright 2025 backnotprop Licensed under [MIT](../../LICENSE-MIT) or [Apache-2.0](../../LICENSE-APACHE).\n","readmeFilename":"README.md","_rev":"1-959edd454cc7ab80578496843f109a30"}
![\"Watch](\"https://img.youtube.com/vi/_N7uo0EFI-U/maxresdefault.jpg\")
\n\n