open-plan-annotator 0.1.1

package/README.md

@@ -0,0 +1,61 @@
+# open-plan-annotator
+
+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.
+
+Select text to strikethrough, replace, insert, or comment — then approve the plan or request changes.
+
+![](.github/assets/screenshot_001.png)
+> UI for annotating LLM Plans
+
+## 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
+
+The server shuts down after you decide. Everything runs locally, nothing leaves your machine.
+
+## Install
+
+```sh
+bun install
+bun run build
+```
+
+This produces a single compiled binary at `build/open-plan-annotator`. Add it to your `PATH`, then install the plugin in Claude Code:
+
+```sh
+claude plugin add /path/to/open-plan-annotator/plugin
+```
+
+## Annotations
+
+| Type | Shortcut | Description |
+|------|----------|-------------|
+| Delete | `d` | Strikethrough selected text |
+| Replace | `r` | Replace selected text with new text |
+| Insert | `i` | Insert text after selection |
+| Comment | `c` | Attach a comment to selected text |
+
+Global shortcuts: `Cmd+Enter` to approve, `Cmd+Shift+Enter` to request changes.
+
+## 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
+```
+
+## License
+
+MIT

package/bin/open-plan-annotator

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const binaryPath = path.join(__dirname, "open-plan-annotator-binary");
+
+if (!fs.existsSync(binaryPath)) {
+  console.error(
+    "open-plan-annotator: binary not found. The postinstall script may have failed.\n" +
+    "Try running: node " + path.join(__dirname, "..", "install.cjs")
+  );
+  process.exit(1);
+}
+
+try {
+  execFileSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+} catch (e) {
+  process.exit(e.status || 1);
+}

package/install.cjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+// Skip postinstall during local development
+if (process.env.OPEN_PLAN_ANNOTATOR_SKIP_INSTALL || process.env.npm_config_dev) {
+  process.exit(0);
+}
+
+const fs = require("fs");
+const path = require("path");
+const zlib = require("zlib");
+const https = require("https");
+
+const VERSION = require("./package.json").version;
+const REPO = "ndomino/open-plan-annotator";
+
+const PLATFORM_MAP = {
+  "darwin-arm64": "open-plan-annotator-darwin-arm64",
+  "darwin-x64": "open-plan-annotator-darwin-x64",
+  "linux-x64": "open-plan-annotator-linux-x64",
+  "linux-arm64": "open-plan-annotator-linux-arm64",
+};
+
+function getPlatformKey() {
+  return `${process.platform}-${process.arch}`;
+}
+
+function getDownloadUrl() {
+  const key = getPlatformKey();
+  const asset = PLATFORM_MAP[key];
+  if (!asset) {
+    console.error(`open-plan-annotator: unsupported platform ${key}`);
+    console.error(`Supported: ${Object.keys(PLATFORM_MAP).join(", ")}`);
+    process.exit(1);
+  }
+  return `https://github.com/${REPO}/releases/download/v${VERSION}/${asset}.tar.gz`;
+}
+
+function fetch(url, redirects) {
+  if (redirects === undefined) redirects = 5;
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, { headers: { "User-Agent": "open-plan-annotator-install" } }, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          if (redirects <= 0) return reject(new Error("Too many redirects"));
+          return fetch(res.headers.location, redirects - 1).then(resolve, reject);
+        }
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          return reject(new Error(`HTTP ${res.statusCode} from ${url}`));
+        }
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on("end", () => resolve(Buffer.concat(chunks)));
+      })
+      .on("error", reject);
+  });
+}
+
+function extractBinaryFromTarGz(buffer) {
+  const tarBuffer = zlib.gunzipSync(buffer);
+  let offset = 0;
+
+  while (offset < tarBuffer.length) {
+    const header = tarBuffer.subarray(offset, offset + 512);
+    offset += 512;
+
+    const name = header.toString("utf-8", 0, 100).replace(/\0.*/g, "");
+    const sizeStr = header.toString("utf-8", 124, 136).replace(/\0.*/g, "").trim();
+    const size = parseInt(sizeStr, 8);
+
+    if (!name || isNaN(size)) break;
+
+    if (name === "open-plan-annotator" || name.endsWith("/open-plan-annotator")) {
+      return tarBuffer.subarray(offset, offset + size);
+    }
+
+    offset += Math.ceil(size / 512) * 512;
+  }
+
+  throw new Error("Binary 'open-plan-annotator' not found in archive");
+}
+
+async function main() {
+  const destDir = path.join(__dirname, "bin");
+  const destPath = path.join(destDir, "open-plan-annotator-binary");
+
+  // Skip if binary already exists
+  if (fs.existsSync(destPath)) {
+    return;
+  }
+
+  const url = getDownloadUrl();
+  console.log(`Downloading open-plan-annotator for ${getPlatformKey()}...`);
+
+  const buffer = await fetch(url);
+  const binaryBuffer = extractBinaryFromTarGz(buffer);
+
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+
+  fs.writeFileSync(destPath, binaryBuffer, { mode: 0o755 });
+  console.log(`Installed open-plan-annotator to ${destPath}`);
+}
+
+main().catch((err) => {
+  console.error("Failed to install open-plan-annotator binary:", err.message);
+  console.error("You can try manually running: node", path.join(__dirname, "install.cjs"));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "open-plan-annotator",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Fully local plugin for interactive plan annotation from your Agentic assistants",
+  "author": "ndomino",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ndomino/open-plan-annotator.git"
+  },
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "plan-mode",
+    "annotation",
+    "code-review"
+  ],
+  "bin": {
+    "open-plan-annotator": "bin/open-plan-annotator"
+  },
+  "files": [
+    "bin/open-plan-annotator",
+    "install.cjs",
+    "plugin/",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node install.cjs",
+    "build:ui": "cd ui && bun run vite build",
+    "build:platforms": "node scripts/build-platforms.cjs",
+    "build": "bun run build:ui && node scripts/build-platforms.cjs",
+    "tarball": "node scripts/tarball.cjs",
+    "release": "bun run build && node scripts/tarball.cjs",
+    "dev:ui": "cd ui && bun run vite --port 5173",
+    "dev:server": "NODE_ENV=development bun run server/index.ts",
+    "dev": "NODE_ENV=development bun run server/index.ts & cd ui && bun run vite --port 5173",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "publish": "./scripts/release.sh"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.4"
+  }
+}

package/plugin/CLAUDE.md

@@ -0,0 +1,28 @@
+# open-plan-annotator: Plan Review Instructions
+
+## ALWAYS Use Plan Mode for Non-Trivial Tasks
+
+Before beginning any implementation that involves:
+- 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
+
+You MUST use plan mode to present your approach first.
+
+## Why This Matters
+
+The user has installed the open-plan-annotator plugin specifically to review and annotate your plans before you write code. Skipping plan mode bypasses this workflow entirely and removes the user's ability to give structured feedback.
+
+## 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
+
+## When Plan Mode Is Optional
+
+For truly trivial tasks (fix a typo, rename a single variable, answer a factual question), plan mode is not required. When in doubt, use it anyway — the user can always approve immediately.

package/plugin/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PermissionRequest": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "open-plan-annotator",
+            "timeout": 345600
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "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.1.1",
+  "author": {
+    "name": "ndomino"
+  },
+  "keywords": [
+    "planning",
+    "review",
+    "hooks",
+    "ExitPlanMode",
+    "annotations"
+  ]
+}