open-plan-annotator 0.2.3 → 0.2.4

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "open-plan-annotator",
       "source": "./",
       "description": "Interactive plan annotation UI: review, strikethrough, and comment on Claude's plans before approving. Fully local, no external services.",
-      "version": "0.2.3",
+      "version": "0.2.4",
       "author": {
         "name": "ndom91"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "open-plan-annotator",
   "description": "Interactive plan annotation UI: review, strikethrough, and comment on Claude's plans before approving. Fully local, no external services.",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "author": {
     "name": "ndom91"
   },

package/README.md

@@ -4,22 +4,21 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-pink?style=flat-square)]()
 
-A fully local agentic coding plugin (claude-code, opencode) that intercepts plan mode, opens an annotation UI in your browser, and feeds structured feedback back to the agent.
+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 accept.
 
 Select text to <code style="color: purple">strikethrough</code>, <code style="color: orange">replace</code>, <code style="color: blue">insert</code>, or <code style="color: red">comment</code> — then approve the plan or request changes.
 
 
-![](.github/assets/screenshot_01.png)
+![](.github/assets/screenshot_1.png)
 
 
 ## How it works
 
-1. Claude calls `ExitPlanMode`
-2. A `PermissionRequest` hook launches the `open-plan-annotator` binary
-3. An ephemeral HTTP server starts and opens a React UI in your browser
-4. You review and annotate the plan
-5. **Approve** — Claude proceeds with the plan
-6. **Request Changes** — annotations are serialized as structured feedback and Claude revises
+1. Host submits a plan to `open-plan-annotator`
+2. An ephemeral HTTP server starts and opens a React UI in your browser
+3. You review and annotate the plan
+4. **Approve** or **Request Changes**
+5. The tool returns host-specific JSON output (Claude hook output or OpenCode plugin output)
 
 The server shuts down after you decide. Everything runs locally, nothing leaves your machine.
 
@@ -38,7 +37,9 @@ This JS shim downloads the correct binary for your platform (macOS, Linux).
 > 'open-plan-annotator' manually to trigger a download, or the first invocation
 > by Claude will also trigger the binary download.
 
-**2. Add the marketplace and install the plugin**
+### Claude Code
+
+Add the marketplace and install the plugin:
 
 From within Claude Code:
 
@@ -54,7 +55,46 @@ This registers the `ExitPlanMode` hook that launches the annotation UI.
 > The first run might take a few seconds if you hadn't installed the binary, as
 > Claude will trigger the download then.
 
-### From source
+### OpenCode
+
+The OpenCode plugin uses the `@opencode-ai/plugin` SDK to register a `submit_plan` tool and inject system prompt instructions that tell the agent to use plan mode.
+
+**Option A: Install from npm (recommended)**
+
+```sh
+npm install -g open-plan-annotator
+cd /path/to/your/project
+open-plan-annotator-install-opencode
+```
+
+This installs the plugin to `.opencode/plugins/open-plan-annotator` and runs `bun install` / `npm install` for its dependencies.
+
+Then register it in your project's `opencode.json`:
+
+```json
+{
+  "plugin": [".opencode/plugins/open-plan-annotator"]
+}
+```
+
+**Option B: From source**
+
+```sh
+git clone https://github.com/ndom91/open-plan-annotator.git
+cd open-plan-annotator
+bun install
+bun run install:opencode-plugin   # installs to .opencode/plugins/ in CWD
+```
+
+Then register in `opencode.json` as above.
+
+The plugin automatically:
+- 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
+
+### From source (Claude Code)
 
 ```sh
 git clone https://github.com/ndom91/open-plan-annotator.git

package/bin/open-plan-annotator-install-opencode.cjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require("../scripts/install-opencode-plugin.cjs");

package/opencode-plugin/index.ts

@@ -0,0 +1,174 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { type Plugin, tool } from "@opencode-ai/plugin";
+
+function resolveRunner(): { command: string; args: string[] } {
+  const moduleDir = dirname(new URL(import.meta.url).pathname);
+  const repoRoot = join(moduleDir, "..");
+  const sourceServer = join(repoRoot, "server", "index.ts");
+  const packageBin = join(repoRoot, "bin", "open-plan-annotator.cjs");
+  const projectLocal = join(process.cwd(), "node_modules", ".bin", "open-plan-annotator");
+
+  if (existsSync(sourceServer) && process.env.OPEN_PLAN_ANNOTATOR_FORCE_BINARY !== "1") {
+    return { command: "bun", args: ["run", sourceServer] };
+  }
+
+  if (existsSync(packageBin)) {
+    return { command: process.execPath, args: [packageBin] };
+  }
+
+  if (existsSync(projectLocal)) {
+    return { command: projectLocal, args: [] };
+  }
+
+  return { command: "open-plan-annotator", args: [] };
+}
+
+function execAsync(
+  command: string,
+  args: string[],
+  stdinData: string,
+): Promise<{ stdout: string; stderr: string; status: number | null }> {
+  return new Promise((resolve) => {
+    const child = execFile(
+      command,
+      args,
+      { encoding: "utf8", maxBuffer: 10 * 1024 * 1024 },
+      (error, stdout, stderr) => {
+        resolve({
+          stdout: stdout ?? "",
+          stderr: stderr ?? "",
+          status: error ? 1 : 0,
+        });
+      },
+    );
+    if (child.stdin) {
+      child.stdin.write(stdinData);
+      child.stdin.end();
+    }
+  });
+}
+
+function normalizeOutput(
+  stdout: string,
+  stderr: string,
+  _status: number | null,
+): { ok: boolean; decision: string; feedback?: string; message?: string } {
+  const text = (stdout ?? "").trim();
+  if (!text) {
+    return {
+      ok: false,
+      decision: "deny",
+      feedback: stderr || "open-plan-annotator returned empty output",
+      message: "Plan changes requested.",
+    };
+  }
+
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === "object") return parsed;
+  } catch {
+    // fall through
+  }
+
+  return {
+    ok: false,
+    decision: "deny",
+    feedback: `Unexpected response from open-plan-annotator: ${text}`,
+    message: "Plan changes requested.",
+  };
+}
+
+const SYSTEM_INSTRUCTIONS = `
+## Plan Submission
+
+When you have completed your plan, you MUST call the \`submit_plan\` tool to submit it for user review.
+The user will be able to:
+- Review your plan visually in a dedicated UI
+- Annotate specific sections with feedback
+- Approve the plan to proceed with implementation
+- Request changes with detailed feedback
+
+If your plan is rejected, you will receive the user's annotated feedback. Revise your plan
+based on their feedback and call submit_plan again.
+
+Do NOT proceed with implementation until your plan is approved.
+
+### When to Use Plan Mode
+
+Use plan mode (and submit your plan for review) for any task involving:
+- Creating or modifying more than 2 files
+- Architectural or structural changes
+- Anything the user hasn't explicitly described step-by-step
+- Refactoring, migration, or feature additions
+- Bug fixes that require investigation
+
+For truly trivial tasks (fix a typo, rename a single variable, answer a factual question), you may skip plan submission.
+
+### Plan Quality Standards
+
+When writing a plan, include:
+- A brief summary of what you understood the task to require
+- The specific files you intend to create or modify and why
+- Any assumptions you are making
+- An explicit question if anything is ambiguous
+`;
+
+export const OpenPlanAnnotatorPlugin: Plugin = async (_ctx) => {
+  return {
+    "experimental.chat.system.transform": async (_input, output) => {
+      output.system.push(SYSTEM_INSTRUCTIONS);
+    },
+
+    tool: {
+      submit_plan: tool({
+        description:
+          "Submit your completed plan for interactive user review. The user can annotate, approve, or request changes. Call this when you have finished creating your implementation plan.",
+        args: {
+          plan: tool.schema.string().describe("The complete implementation plan in markdown format"),
+          summary: tool.schema
+            .string()
+            .optional()
+            .describe("A brief 1-2 sentence summary of what the plan accomplishes"),
+        },
+
+        async execute(args) {
+          const runner = resolveRunner();
+          const payload = JSON.stringify({
+            host: "opencode",
+            command: "submit_plan",
+            plan: args.plan,
+            cwd: process.cwd(),
+          });
+
+          const result = await execAsync(runner.command, runner.args, payload);
+          const output = normalizeOutput(result.stdout, result.stderr, result.status);
+
+          if (output.ok && output.decision === "approve") {
+            return [
+              "Plan approved by the user. You may now proceed with implementation.",
+              args.summary ? `\nPlan Summary: ${args.summary}` : "",
+            ].join("");
+          }
+
+          return [
+            "Plan needs revision.",
+            "",
+            "The user has requested changes to your plan. Please review their feedback below and revise your plan accordingly.",
+            "",
+            "## User Feedback",
+            "",
+            output.feedback ?? "Plan changes requested.",
+            "",
+            "---",
+            "",
+            "Please revise your plan based on this feedback and call `submit_plan` again when ready.",
+          ].join("\n");
+        },
+      }),
+    },
+  };
+};
+
+export default OpenPlanAnnotatorPlugin;

package/opencode-plugin/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "open-plan-annotator-opencode",
+  "version": "0.2.3",
+  "description": "Open Plan Annotator plugin for OpenCode - interactive plan review with visual annotation",
+  "author": "ndom91",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ndom91/open-plan-annotator.git",
+    "directory": "opencode-plugin"
+  },
+  "main": "index.ts",
+  "files": [
+    "index.ts",
+    "package.json"
+  ],
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.0.218"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-plan-annotator",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "type": "module",
   "description": "Fully local plugin for interactive plan annotation from your Agentic assistants",
   "author": "ndom91",
@@ -11,21 +11,26 @@
   },
   "keywords": [
     "claude-code",
+    "opencode",
     "plugin",
     "plan-mode",
     "annotation",
     "code-review"
   ],
   "bin": {
-    "open-plan-annotator": "bin/open-plan-annotator.cjs"
+    "open-plan-annotator": "bin/open-plan-annotator.cjs",
+    "open-plan-annotator-install-opencode": "bin/open-plan-annotator-install-opencode.cjs"
   },
   "files": [
     "bin/open-plan-annotator.cjs",
+    "bin/open-plan-annotator-install-opencode.cjs",
     "install.cjs",
     ".claude-plugin/",
+    "opencode-plugin/",
     "hooks/",
     "CLAUDE.md",
-    "README.md"
+    "README.md",
+    "scripts/install-opencode-plugin.cjs"
   ],
   "scripts": {
     "postinstall": "node install.cjs",
@@ -41,6 +46,7 @@
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
+    "install:opencode-plugin": "node scripts/install-opencode-plugin.cjs",
     "do-release": "./scripts/release.sh",
     "prepack": "mv CLAUDE.md CLAUDE.dev.md.bak && cp CLAUDE.plugin.md CLAUDE.md",
     "postpack": "mv CLAUDE.dev.md.bak CLAUDE.md"

package/scripts/install-opencode-plugin.cjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+function resolveTargetRoot() {
+  const fromArg = process.argv[2];
+  if (fromArg && fromArg.trim().length > 0) {
+    return path.resolve(process.cwd(), fromArg);
+  }
+  return path.resolve(process.cwd(), ".opencode", "plugins");
+}
+
+function ensureParentDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function installPlugin(sourceDir, destinationDir) {
+  if (fs.existsSync(destinationDir)) {
+    fs.rmSync(destinationDir, { recursive: true, force: true });
+  }
+
+  try {
+    fs.symlinkSync(sourceDir, destinationDir, "dir");
+    return "symlink";
+  } catch {
+    fs.cpSync(sourceDir, destinationDir, { recursive: true });
+    return "copy";
+  }
+}
+
+function main() {
+  const projectRoot = path.resolve(__dirname, "..");
+  const sourceDir = path.join(projectRoot, "opencode-plugin");
+  const targetRoot = resolveTargetRoot();
+  const destinationDir = path.join(targetRoot, "open-plan-annotator");
+
+  if (!fs.existsSync(sourceDir)) {
+    console.error(`open-plan-annotator: missing opencode-plugin at ${sourceDir}`);
+    process.exit(1);
+  }
+
+  ensureParentDir(targetRoot);
+  const mode = installPlugin(sourceDir, destinationDir);
+
+  console.log(
+    `open-plan-annotator: installed OpenCode plugin (${mode}) at ${destinationDir}`,
+  );
+
+  // Install plugin dependencies using the first available package manager
+  const { execFileSync } = require("child_process");
+  const packageManagers = [
+    { cmd: "bun", args: ["install"] },
+    { cmd: "pnpm", args: ["install"] },
+    { cmd: "npm", args: ["install"] },
+  ];
+
+  let installed = false;
+  for (const pm of packageManagers) {
+    try {
+      execFileSync(pm.cmd, pm.args, { cwd: destinationDir, stdio: "inherit" });
+      installed = true;
+      break;
+    } catch {
+      // Try the next package manager
+    }
+  }
+
+  if (!installed) {
+    console.log(
+      "open-plan-annotator: could not install dependencies automatically. Run `npm install` in:",
+      destinationDir,
+    );
+  }
+
+  console.log(
+    '\nTo activate, add to your opencode.json:\n  { "plugin": [".opencode/plugins/open-plan-annotator"] }',
+  );
+}
+
+main();