@insitue/claude-plugin 0.0.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "insitue",
+  "version": "0.0.1",
+  "description": "Drive a Claude Code session from the InSitue browser overlay. Pick an element in your app, claude reads the file and proposes the edit.",
+  "mcpServers": {
+    "insitue": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp-server.js"],
+      "cwd": "${CLAUDE_PROJECT_DIR}"
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rod Leviton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @insitue/claude-plugin
+
+Drive a Claude Code session from the InSitue browser overlay. Pick an
+element in your running app, claude reads the file and proposes the
+edit — no copy/paste of file paths, no typing line numbers.
+
+## What you get
+
+- A namespaced slash command **`/insitue:connect`** that puts the
+  current `claude` session into "watch InSitue" mode.
+- An MCP server (`insitue`) with two tools:
+  - `insitue__next_pick` — long-polls until the next pick lands.
+  - `insitue__list_recent_picks` — replays recent picks (e.g. things
+    you selected before claude attached).
+
+The bridge connects to the same loopback companion the browser
+overlay uses (reads `.insitu/session.json` from your project), so
+there's no extra config — start `insitue dev`, start `claude`, run
+`/insitue:connect`, click in the browser.
+
+## Install
+
+```bash
+claude plugin install @insitue/claude-plugin
+```
+
+## Use
+
+Three terminals:
+
+```bash
+# Terminal A — your dev server (the app you're editing)
+pnpm dev    # or npm run dev, etc.
+
+# Terminal B — the InSitue companion (writes .insitu/session.json)
+npx insitue dev
+
+# Terminal C — Claude Code
+claude
+> /insitue:connect
+```
+
+Now click **Select** in the InSitue overlay, pick an element, and
+type your request in the panel's "User note" field. Claude in
+Terminal C reads the file at the exact location, proposes the diff,
+and waits for your "approve" before writing.
+
+## Architecture
+
+```
+┌───────────────────┐         ┌───────────────────┐
+│  Browser overlay  │ ──WS──▶ │ Local companion   │
+│   (insitue/sdk)   │         │  (insitue dev)    │
+└───────────────────┘         └─────────┬─────────┘
+                                        │ WS broadcast-capture
+                                        ▼
+                              ┌───────────────────┐
+                              │ @insitue/         │
+                              │ claude-plugin     │ ◀── stdio MCP ──┐
+                              │  (MCP bridge)     │                 │
+                              └───────────────────┘                 │
+                                                          ┌─────────┴───────┐
+                                                          │ claude (CLI)    │
+                                                          │ /insitue:connect│
+                                                          └─────────────────┘
+```
+
+The bridge never writes files — it just hands picks to `claude`, and
+`claude` proposes edits through its normal Edit/Write tools (which
+still respect your `claude` permissions).
+
+## License
+
+MIT — same as the rest of InSitue.

package/commands/connect.md

@@ -0,0 +1,35 @@
+---
+description: Watch the InSitue browser overlay and act on each pick. Reads picks from the running local InSitue companion, edits the file the user pointed at, asks for confirmation, loops.
+---
+
+# /insitue:connect
+
+Connect this Claude Code session to the running InSitue companion and turn each browser pick into a real code change.
+
+## How it works
+
+1. The user runs `npx insitue dev` in their project (the companion).
+2. The user clicks **Select** in the InSitue browser overlay, then picks an element.
+3. Claude (you) calls `mcp__insitue__next_pick` — blocks until a pick lands.
+4. The tool returns the resolved `file:line`, component name, the user's note (what they typed in the panel), and surrounding context.
+5. You read the file at the returned path, propose the edit, show the diff, and ask the user **here in chat** to approve before writing.
+6. After applying, you call `next_pick` again and the loop continues.
+
+## Your behavior on /insitue:connect
+
+- **First**, call `mcp__insitue__list_recent_picks` once to see if the user already picked things before attaching. If there are recent picks the user hasn't acted on, summarise them so they can choose which to address.
+- **Then enter the loop**: call `mcp__insitue__next_pick`. It blocks for ~5 min by default. When it returns:
+  - If `status: "ok"`: read the `pick.source.file` at `pick.source.line`, plus a few surrounding lines for context.
+  - The `pick.userNote` is the user's instruction. If empty, ask "What would you like to change at `<componentName>` (`<file>:<line>`)?" before doing anything.
+  - Propose an edit. Show a small diff in chat. Wait for the user to say "go" / "approve" / "yes" before writing.
+  - On approval, apply with Edit/Write. Confirm what changed.
+  - Loop back to `next_pick`.
+- **If a pick comes through with `target` starting with `[insitue]`**: the companion disconnected (HMR / restart). Tell the user, then call `next_pick` again — the bridge auto-reconnects.
+- **Exit the loop** when the user says "stop", "done", "quit", or similar.
+
+## Guardrails
+
+- Don't touch any file outside the pick's `pick.source.file` unless the user explicitly asks for cross-file changes.
+- Don't auto-approve. Every write is gated by an explicit user "yes" in chat.
+- If `pick.source` is `null` (selector-only pick), don't guess — tell the user the source wasn't resolved and ask which file to edit.
+- If `pick.confidence` is `"approximate"` (owner-fiber fallback, not the exact JSX site), warn the user before editing.

package/dist/mcp-server.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+
+// src/mcp-server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { existsSync, readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import WebSocket from "ws";
+import { z } from "zod";
+var MAX_BUFFERED_PICKS = 32;
+var NEXT_PICK_DEFAULT_TIMEOUT_MS = 5 * 60 * 1e3;
+var NEXT_PICK_MAX_TIMEOUT_MS = 30 * 60 * 1e3;
+function findSession(start = process.cwd()) {
+  let dir = resolve(start);
+  while (true) {
+    const candidate = join(dir, ".insitu", "session.json");
+    if (existsSync(candidate)) {
+      try {
+        const session = JSON.parse(readFileSync(candidate, "utf8"));
+        return { dir, session };
+      } catch {
+        return null;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function summariseBundle(raw) {
+  const t = raw.bundle.target ?? null;
+  const componentStack = (t?.componentStack ?? []).map((c) => ({
+    name: c.name,
+    ...c.source?.file ? { file: c.source.file } : {},
+    ...c.source?.line ? { line: c.source.line } : {}
+  }));
+  const target = componentStack[0]?.name ?? (t?.selector ? t.selector.split(" ").slice(-1)[0] : "?");
+  return {
+    id: raw.id,
+    at: raw.at,
+    source: raw.resolved?.file ? {
+      file: raw.resolved.file,
+      ...raw.resolved.line ? { line: raw.resolved.line } : {}
+    } : t?.source ? { file: t.source.file, ...t.source.line ? { line: t.source.line } : {} } : null,
+    confidence: raw.resolved?.confidence ?? t?.confidence ?? "unknown",
+    target,
+    selector: t?.selector ?? null,
+    userNote: raw.bundle.userNote ?? null,
+    url: raw.bundle.runtime?.url ?? null,
+    componentStack
+  };
+}
+var PickBuffer = class {
+  picks = [];
+  waiters = [];
+  /** Last pick id handed out via `next_pick` — defends against
+   *  re-delivering the same pick across reconnects. */
+  lastDelivered = null;
+  push(p) {
+    this.picks.push(p);
+    if (this.picks.length > MAX_BUFFERED_PICKS) {
+      this.picks.shift();
+    }
+    while (this.waiters.length && this.picks.length) {
+      const w = this.waiters.shift();
+      clearTimeout(w.timer);
+      const next = this.picks.shift();
+      this.lastDelivered = next.id;
+      w.resolve(next);
+    }
+  }
+  /** Resolve with the next pick to land OR null on timeout. */
+  next(timeoutMs) {
+    if (this.picks.length) {
+      const next = this.picks.shift();
+      this.lastDelivered = next.id;
+      return Promise.resolve(next);
+    }
+    return new Promise((resolve2) => {
+      const timer = setTimeout(() => {
+        const idx = this.waiters.findIndex((w) => w.timer === timer);
+        if (idx >= 0) this.waiters.splice(idx, 1);
+        resolve2(null);
+      }, timeoutMs);
+      this.waiters.push({ resolve: resolve2, timer });
+    });
+  }
+  recent(limit) {
+    return this.picks.slice(-limit);
+  }
+  /** When the WS reconnects, drop pending waiters with a sentinel so
+   *  claude sees the disruption instead of hanging forever. */
+  rejectAll(reason) {
+    for (const w of this.waiters) {
+      clearTimeout(w.timer);
+      w.resolve({
+        id: "reconnect",
+        at: (/* @__PURE__ */ new Date()).toISOString(),
+        source: null,
+        confidence: "n/a",
+        target: `[insitu] ${reason}`,
+        selector: null,
+        userNote: null,
+        url: null,
+        componentStack: []
+      });
+    }
+    this.waiters.length = 0;
+  }
+};
+var buffer = new PickBuffer();
+function connectToCompanion(session) {
+  const url = `ws://127.0.0.1:${session.port}/insitu/cli`;
+  const ws = new WebSocket(url, {
+    headers: { "user-agent": "insitue-claude-plugin/0.0.1" }
+  });
+  ws.on("open", () => {
+    ws.send(
+      JSON.stringify({
+        t: "hello",
+        // Pin to the published companion protocol version — bumped
+        // when the wire format breaks, NOT for every release.
+        protocolVersion: 4,
+        token: session.token
+      })
+    );
+  });
+  ws.on("message", (data) => {
+    let m;
+    try {
+      m = JSON.parse(String(data));
+    } catch {
+      return;
+    }
+    if (m && typeof m === "object" && m.t === "hello-ok") {
+      ws.send(JSON.stringify({ t: "subscribe" }));
+      return;
+    }
+    if (m && typeof m === "object" && m.t === "broadcast-capture") {
+      try {
+        buffer.push(summariseBundle(m));
+      } catch (err) {
+        process.stderr.write(
+          `[insitue-mcp] dropped malformed pick: ${err.message}
+`
+        );
+      }
+    }
+  });
+  ws.on("close", () => {
+    buffer.rejectAll("companion disconnected \u2014 restart `insitue dev`?");
+    setTimeout(() => connectToCompanion(session), 2e3);
+  });
+  ws.on("error", () => {
+  });
+}
+var found = findSession();
+if (!found) {
+  process.stderr.write(
+    "[insitue-mcp] no `.insitu/session.json` found in cwd or any parent.\n  Start the companion first: `npx insitue dev` from your project root.\n"
+  );
+  process.exit(1);
+}
+connectToCompanion(found.session);
+var server = new McpServer({
+  name: "insitue",
+  version: "0.0.1"
+});
+server.registerTool(
+  "next_pick",
+  {
+    description: 'Long-polls for the next element the user picks in the InSitue browser overlay. Returns the resolved source location (file + line), component name, optional user note, and surrounding context (URL, selector, component stack). Use this in a loop: call \u2192 wait \u2192 edit the returned file \u2192 call again. Returns a special `target: "[insitue] ..."` envelope on companion disconnect.',
+    inputSchema: {
+      timeout_ms: z.number().int().positive().max(NEXT_PICK_MAX_TIMEOUT_MS).optional().describe(
+        `How long to wait for the next pick (ms). Default ${NEXT_PICK_DEFAULT_TIMEOUT_MS}; max ${NEXT_PICK_MAX_TIMEOUT_MS}.`
+      )
+    }
+  },
+  async ({ timeout_ms }) => {
+    const ms = timeout_ms ?? NEXT_PICK_DEFAULT_TIMEOUT_MS;
+    const pick = await buffer.next(ms);
+    if (!pick) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ status: "timeout", waited_ms: ms })
+          }
+        ]
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ status: "ok", pick })
+        }
+      ]
+    };
+  }
+);
+server.registerTool(
+  "list_recent_picks",
+  {
+    description: "Returns up to N most-recent picks buffered since the MCP server started. Use this once at session start to see what the user already selected before claude attached, or to re-read context without consuming a pick.",
+    inputSchema: {
+      limit: z.number().int().positive().max(MAX_BUFFERED_PICKS).optional().describe(`Max picks to return (1..${MAX_BUFFERED_PICKS}). Default 10.`)
+    }
+  },
+  async ({ limit }) => {
+    const picks = buffer.recent(limit ?? 10);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ count: picks.length, picks })
+        }
+      ]
+    };
+  }
+);
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@insitue/claude-plugin",
+  "version": "0.0.1",
+  "description": "Drive a Claude Code session from the InSitue browser overlay — pick an element in your app, claude reads the file and proposes the edit.",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    ".claude-plugin",
+    "commands",
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./dist/mcp-server.js"
+  },
+  "bin": {
+    "insitue-mcp": "./dist/mcp-server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ws": "^8.18.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.13",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/mcp-server.ts --format esm --clean --external @modelcontextprotocol/sdk --external ws --external zod",
+    "dev": "tsup src/mcp-server.ts --format esm --watch --external @modelcontextprotocol/sdk --external ws --external zod",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  }
+}