Move plugins to single binary runtime

OpenCode and Pi now discover and call the plannotator binary instead of
bundling their own server implementations. Adds plugin protocol, binary
discovery, capability checks, and auto-install bridge.

Author: backnotprop

.github/workflows/release.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Install dependencies
         run: bun install
 
-      - name: Generate Pi extension shared copies
+      - name: Generate Pi extension shared helpers
         run: bash apps/pi-extension/vendor.sh
 
       - name: Type check

.github/workflows/test.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Install dependencies
         run: bun install
 
-      - name: Generate Pi extension shared copies
+      - name: Generate Pi extension shared helpers
         run: bash apps/pi-extension/vendor.sh
 
       - name: Type check

.gitignore

@@ -52,6 +52,4 @@ opencode.json
 plannotator-local
 # Local research/reference docs (not for repo)
 /reference/
-# Local goal setup packages generated by the setup-goal skill.
-/goals/
 *.bun-build

AGENTS.md

@@ -73,7 +73,10 @@ plannotator/
 │   ├── shared/                   # Shared types, utilities, and cross-runtime logic
 │   │   ├── storage.ts            # Plan saving, version history, archive listing (node:fs only)
 │   │   ├── draft.ts              # Annotation draft persistence (node:fs only)
-│   │   └── project.ts            # Pure string helpers (sanitizeTag, extractRepoName, extractDirName)
+│   │   ├── project.ts            # Pure string helpers (sanitizeTag, extractRepoName, extractDirName)
+│   │   ├── plugin-protocol.ts    # JSON protocol for binary-owned plugin commands
+│   │   ├── plugin-client.ts      # Shared OpenCode/Pi subprocess client for plannotator plugin commands
+│   │   └── plugin-binary.ts      # Binary discovery, compatibility checks, and installer bridge
 │   ├── editor/                   # Plan review app
 │   │   ├── App.tsx               # Main plan review app
 │   │   └── shortcuts.ts          # planReviewSurface + annotateSurface — composes plan-review scopes into per-surface registries
@@ -90,12 +93,11 @@ plannotator/
 
 ## Server Runtimes
 
-There are two separate server implementations with the same API surface:
+Plannotator has one server implementation:
 
-- **Bun server** (`packages/server/`) — used by both Claude Code (`apps/hook/`) and OpenCode (`apps/opencode-plugin/`). These plugins import directly from `@plannotator/server`.
-- **Pi server** (`apps/pi-extension/server/`) — a standalone Node.js server for the Pi extension. It mirrors the Bun server's API but uses `node:http` primitives instead of Bun's `Request`/`Response` APIs.
+- **Bun server** (`packages/server/`) — owns plan review, code review, annotate, archive, and shared browser APIs.
 
-When adding or modifying server endpoints, both implementations must be updated. Runtime-agnostic logic (store, validation, types) lives in `packages/shared/` and is imported by both.
+Claude Code runs this server through the released `plannotator` binary entrypoint. OpenCode and Pi do not package their own server implementations; they call the same binary through the plugin protocol in `packages/shared/plugin-protocol.ts`. Runtime-agnostic logic (store, validation, types) lives in `packages/shared/`.
 
 ## Installation
 
@@ -118,6 +120,8 @@ claude --plugin-dir ./apps/hook
 | `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. |
 | `PLANNOTATOR_PORT` | Fixed port to use. Default: random locally, `19432` for remote sessions. |
 | `PLANNOTATOR_BROWSER` | Custom browser to open plans in. macOS: app name or path. Linux/Windows: executable path. |
+| `PLANNOTATOR_BIN` | Explicit `plannotator` binary path for OpenCode/Pi plugin clients. Overrides PATH and standard install locations. |
+| `PLANNOTATOR_DISABLE_AUTO_INSTALL` | Set to `1` / `true` to make OpenCode/Pi fail clearly instead of running the official installer when no compatible binary is found. |
 | `PLANNOTATOR_SHARE` | Set to `disabled` to turn off URL sharing entirely. Default: enabled. |
 | `PLANNOTATOR_SHARE_URL` | Custom base URL for share links (self-hosted portal). Default: `https://share.plannotator.ai`. |
 | `PLANNOTATOR_PASTE_URL` | Base URL of the paste service API for short URL sharing. Default: `https://plannotator-paste.plannotator.workers.dev`. |

apps/copilot/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plannotator-copilot",
   "description": "Interactive Plan & Code Review for GitHub Copilot CLI. Visual annotations, team sharing, structured feedback.",
-  "version": "0.19.18",
+  "version": "0.19.17",
   "author": { "name": "backnotprop" },
   "repository": "https://github.com/backnotprop/plannotator",
   "license": "MIT OR Apache-2.0",

apps/hook/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plannotator",
   "description": "Interactive Plan Review: Mark up and refine your plans using a UI, easily share for team collaboration, automatically integrates with plan mode hooks.",
-  "version": "0.19.18",
+  "version": "0.19.17",
   "author": {
     "name": "backnotprop"
   },

apps/hook/README.md

@@ -23,6 +23,8 @@ curl -fsSL https://plannotator.ai/install.cmd -o install.cmd && install.cmd && d
 
 Released binaries ship with SHA256 sidecars and [SLSA build provenance](https://slsa.dev/) attestations from v0.17.2 onwards. See the [installation docs](https://plannotator.ai/docs/getting-started/installation/#verifying-your-install) for version pinning and verification commands.
 
+The released binary owns Plannotator's browser server runtime for Claude Code, OpenCode, and Pi. See [Single Binary Runtime](../../docs/single-binary-runtime.md) for the plugin client boundary and daemon-next design.
+
 ---
 
 [Plugin Installation](#plugin-installation) · [Manual Installation (Hooks)](#manual-installation-hooks) · [Obsidian Integration](#obsidian-integration)  

apps/hook/dev-mock-api.ts

@@ -552,9 +552,6 @@ This change lands in section 3 of the contributor guide alongside the updated re
 const USE_DIFF_DEMO =
   process.env.VITE_DIFF_DEMO === "1" ||
   process.env.VITE_DIFF_DEMO === "true";
-const GOAL_SETUP_DEMO = process.env.VITE_GOAL_SETUP_DEMO;
-const USE_GOAL_SETUP_DEMO =
-  GOAL_SETUP_DEMO === "interview" || GOAL_SETUP_DEMO === "facts";
 
 const PLAN_V1 = USE_DIFF_DEMO ? PLAN_V1_DIFF_TEST : PLAN_V1_DEFAULT;
 const PLAN_V2 = USE_DIFF_DEMO ? PLAN_V2_DIFF_TEST : PLAN_V2_DEFAULT;
@@ -629,153 +626,6 @@ export function devMockApi(): Plugin {
 
         if (req.url === '/api/plan') {
           res.setHeader('Content-Type', 'application/json');
-          if (USE_GOAL_SETUP_DEMO) {
-            res.end(JSON.stringify({
-              plan: '',
-              origin: 'claude-code',
-              mode: 'goal-setup',
-              sharingEnabled: false,
-              goalSetup: GOAL_SETUP_DEMO === "facts" ? {
-                stage: "facts",
-                title: "Interactive goal setup facts",
-                goalSlug: "interactive-goal-setup-ui",
-                facts: [
-                  {
-                    id: "skill-batch",
-                    text: "The setup-goal skill should package all interview questions into one Plannotator UI session.",
-                    accepted: false,
-                    removed: false,
-                    recommendedAutomatedVerification: true,
-                    automatedVerification: true,
-                  },
-                  {
-                    id: "facts-verify",
-                    text: "Each fact can be accepted, edited, removed, commented on, and marked for automated verification.",
-                    accepted: false,
-                    removed: false,
-                    recommendedAutomatedVerification: true,
-                    automatedVerification: true,
-                  },
-                  {
-                    id: "header-submit",
-                    text: "Goal setup submission should use the Plannotator app header action area instead of local form buttons.",
-                    accepted: false,
-                    removed: false,
-                    recommendedAutomatedVerification: false,
-                    automatedVerification: false,
-                  },
-                  {
-                    id: "question-modes",
-                    text: "The interview UI should cover text answers, single-select choices, multi-select choices, and custom option entry.",
-                    accepted: false,
-                    removed: false,
-                    recommendedAutomatedVerification: true,
-                    automatedVerification: true,
-                  },
-                  {
-                    id: "previous",
-                    text: "Previously accepted facts remain visible in the facts review with their accepted state preserved.",
-                    accepted: true,
-                    removed: false,
-                    recommendedAutomatedVerification: false,
-                    automatedVerification: false,
-                  },
-                  {
-                    id: "bulk-accept",
-                    text: "The facts UI provides a single action to accept every visible fact while keeping the review open for final edits.",
-                    accepted: false,
-                    removed: false,
-                    recommendedAutomatedVerification: true,
-                    automatedVerification: true,
-                  },
-                  {
-                    id: "copy-export",
-                    text: "The interview and facts UIs can copy the current state as raw JSON or markdown for provenance and debugging.",
-                    accepted: false,
-                    removed: false,
-                    recommendedAutomatedVerification: false,
-                    automatedVerification: false,
-                  },
-                ],
-              } : {
-                stage: "interview",
-                title: "Interactive goal setup interview",
-                goalSlug: "interactive-goal-setup-ui",
-                questions: [
-                  {
-                    id: "objective",
-                    prompt: "What is the primary outcome of this goal?",
-                    description: "One sentence that captures what 'done' looks like.",
-                    answerMode: "text",
-                    recommendedAnswer: "A bundled goal setup UI where agents launch one browser session for interview Q&A and a second for facts acceptance, replacing multi-turn chat prompting.",
-                  },
-                  {
-                    id: "audience",
-                    prompt: "Which inferred audience assumption should change?",
-                    description: "The agent should not need basic confirmation here; only change this if the default is wrong.",
-                    answerMode: "single",
-                    recommendedAnswer: "Developers using Claude Code with Plannotator installed.",
-                    recommendedOptionIds: ["devs-cc"],
-                    options: [
-                      { id: "devs-cc", label: "Developers on Claude Code" },
-                      { id: "devs-oc", label: "Developers on OpenCode" },
-                      { id: "devs-all", label: "All Plannotator users" },
-                    ],
-                  },
-                  {
-                    id: "scope",
-                    prompt: "Which inferred scope items should stay or be added?",
-                    description: "Recommended items are based on the code paths the agent can infer. Add only missing nuance.",
-                    answerMode: "multi-custom",
-                    recommendedAnswer: "Skill text, interactive UI, server endpoints, and tests.",
-                    recommendedOptionIds: ["skill", "ui", "server", "tests"],
-                    options: [
-                      { id: "skill", label: "Skill text" },
-                      { id: "ui", label: "Interactive UI" },
-                      { id: "server", label: "Server endpoints" },
-                      { id: "tests", label: "Tests and fixtures" },
-                    ],
-                  },
-                  {
-                    id: "launch",
-                    prompt: "What rollout constraint should override the default?",
-                    description: "Default is the smallest useful launch; choose a broader option only if runtime parity matters immediately.",
-                    answerMode: "single",
-                    recommendedOptionIds: ["claude-only"],
-                    options: [
-                      { id: "claude-only", label: "Claude Code only" },
-                      { id: "all-runtimes", label: "All runtimes (Claude Code, OpenCode, Pi)" },
-                      { id: "prototype", label: "Prototype behind a dev flag" },
-                    ],
-                  },
-                  {
-                    id: "risk",
-                    prompt: "Which risks should the plan explicitly address?",
-                    answerMode: "multi",
-                    recommendedOptionIds: ["runtime-parity", "data-loss"],
-                    options: [
-                      { id: "runtime-parity", label: "Runtime parity", description: "Bun and Pi server endpoints stay mirrored." },
-                      { id: "data-loss", label: "Answer data loss", description: "Edited answers survive until submission." },
-                      { id: "header-actions", label: "Header action placement", description: "Submit/close matches existing patterns." },
-                    ],
-                  },
-                  {
-                    id: "facts-ux",
-                    prompt: "How should fact review work?",
-                    answerMode: "text",
-                    recommendedAnswer: "Vertical list with per-fact accept, edit, remove, comment, and automated-verification toggle. Accepted facts hidden by default on re-review.",
-                  },
-                  {
-                    id: "out-of-scope",
-                    prompt: "Anything explicitly out of scope?",
-                    answerMode: "custom",
-                    required: false,
-                  },
-                ],
-              },
-            }));
-            return;
-          }
           res.end(JSON.stringify({
             plan: undefined, // Editor uses its own DIFF_DEMO_PLAN_CONTENT
             origin: 'claude-code',
@@ -786,15 +636,6 @@ export function devMockApi(): Plugin {
           return;
         }
 
-        if (req.url === '/api/goal-setup/submit' && req.method === 'POST') {
-          req.on('data', () => {});
-          req.on('end', () => {
-            res.setHeader('Content-Type', 'application/json');
-            res.end(JSON.stringify({ ok: true }));
-          });
-          return;
-        }
-
         if (req.url === '/api/plan/versions') {
           res.setHeader('Content-Type', 'application/json');
           res.end(JSON.stringify({

apps/hook/server/cli.test.ts

@@ -23,7 +23,7 @@ describe("CLI top-level help", () => {
     expect(output).toContain("plannotator [--browser <name>]");
     expect(output).toContain("plannotator review [--git] [PR_URL]");
     expect(output).toContain("plannotator annotate <file.md | file.html | https://... | folder/>");
-    expect(output).toContain("plannotator setup-goal <interview|facts>");
+    expect(output).toContain("plannotator plugin capabilities");
     expect(output).toContain("running 'plannotator' without arguments is for hook integration");
   });
 });
@@ -56,8 +56,8 @@ describe("interactive no-arg invocation", () => {
     expect(output).toContain("usually launched automatically by Claude Code hooks");
     expect(output).toContain("It expects hook JSON on stdin.");
     expect(output).toContain("plannotator review");
-    expect(output).toContain("plannotator setup-goal interview bundle.json --json");
     expect(output).toContain("plannotator sessions");
+    expect(output).toContain("plannotator plugin capabilities");
     expect(output).toContain("Run 'plannotator --help' for top-level usage.");
   });
 });

apps/hook/server/cli.ts

@@ -27,11 +27,12 @@ export function formatTopLevelHelp(): string {
     "  plannotator [--browser <name>]",
     "  plannotator review [--git] [PR_URL]",
     "  plannotator annotate <file.md | file.html | https://... | folder/>  [--no-jina] [--gate] [--json] [--hook]",
-    "  plannotator setup-goal <interview|facts> <bundle.json | -> [--json]",
     "  plannotator last",
     "  plannotator archive",
+    "  plannotator setup-goal <interview|facts> <bundle.json | -> [--json]",
     "  plannotator sessions",
     "  plannotator improve-context",
+    "  plannotator plugin capabilities",
     "",
     "Note:",
     "  running 'plannotator' without arguments is for hook integration and expects JSON on stdin",
@@ -46,10 +47,10 @@ export function formatInteractiveNoArgClarification(): string {
     "For interactive use, try:",
     "  plannotator review",
     "  plannotator annotate <file.md | file.html | https://...>",
-    "  plannotator setup-goal interview bundle.json --json",
     "  plannotator last",
     "  plannotator archive",
     "  plannotator sessions",
+    "  plannotator plugin capabilities",
     "",
     "Run 'plannotator --help' for top-level usage.",
   ].join("\n");