@insitue/claude-plugin 0.3.3 → 0.4.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "insitue",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "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": {

package/README.md

@@ -1,10 +1,10 @@
-# InSitue Dev — Claude Code plugin
+# InSitue Dev — Claude plugin (Code + Desktop)
 
-Drive a `claude` session from your running app. Pick an element
-in the browser, describe what you want changed, hit Send.
-`claude` reads the file at exactly the right line and proposes
-the edit. No copy-pasting file paths. No fumbling for line
-numbers. The picker IS the prompt.
+Drive a Claude session — **Code or Desktop** — from your running
+app. Pick an element in the browser, describe what you want
+changed, hit Send. claude reads the file at exactly the right
+line and proposes the edit. No copy-pasting file paths. No
+fumbling for line numbers. The picker IS the prompt.
 
 ```
    ┌────────────────────────────────┐         ┌────────────────────┐
@@ -26,7 +26,14 @@ numbers. The picker IS the prompt.
 
 ## Setup (60 seconds, one-time)
 
-### 1. Install the plugin
+Pick your runtime:
+
+- **Claude Code** (the CLI / terminal app) → §1A below.
+- **Claude Desktop** (the macOS / Windows app) → §1B below.
+
+If you use both, do both — same MCP, same widget, same picks.
+
+### 1A. Claude Code — install via the marketplace
 
 In any `claude` session:
 
@@ -37,7 +44,57 @@ In any `claude` session:
 
 That's it for the plugin side. The MCP server it ships will
 auto-start the InSitue companion process in the background of
-your `claude` session — no separate terminal to babysit.
+your `claude` session — no separate terminal to babysit. The
+slash command `/insitue:connect` enters the loop.
+
+### 1B. Claude Desktop — one-command setup
+
+Claude Desktop doesn't have a plugin marketplace, but it does
+load MCP servers from `claude_desktop_config.json`. The package
+ships an `insitue` CLI that writes the right entry for you:
+
+```bash
+# from your project directory
+npx -y @insitue/claude-plugin setup --desktop
+```
+
+What it does (all idempotent + backed up):
+
+1. Detects your OS and finds the Desktop config file
+   (`~/Library/Application Support/Claude/claude_desktop_config.json`
+   on macOS, `%APPDATA%\Claude\…` on Windows,
+   `$XDG_CONFIG_HOME/Claude/…` on Linux).
+2. Backs up the existing file with an `.insitue-backup-<timestamp>`
+   suffix.
+3. Adds (or updates) a `mcpServers["insitue-<projectname>"]`
+   entry pointing at `npx -y @insitue/claude-plugin@latest`
+   with `INSITUE_PROJECT_DIR` set to your project.
+
+Restart Claude Desktop, open a new chat, and type:
+
+> Use the InSitue MCP — call `start_session`.
+
+claude fetches the operating instructions, attaches to the
+companion, and enters the loop. The slash command on Code and
+`start_session` on Desktop deliver the exact same content.
+
+**Multi-project?** Run `setup --desktop --project=/path/to/other`
+in each project root. Each gets its own MCP entry
+(`insitue-<dirname>`), so switching between projects in Desktop
+is just picking the right server-prefix in chat.
+
+**Want to see what would change first?** Append `--dry-run`. The
+CLI prints the JSON entry without touching the file.
+
+**Diagnose a setup that's misbehaving:**
+
+```bash
+npx -y @insitue/claude-plugin diagnose
+```
+
+Reports project dir, session file freshness, companion
+reachability, SDK + SWC-plugin versions + wiring, and concrete
+recommendations.
 
 ### 2. Mount the widget in your app
 

package/commands/connect.md

@@ -1,18 +1,30 @@
 ---
-description: Drive this Claude Code session from the InSitue browser overlay — pick + describe in the browser, claude acts in the terminal.
+description: Drive this Claude session (Code or Desktop) from the InSitue browser overlay — pick + describe in the browser, claude acts here.
 ---
 
-# /insitue:connect
+# InSitue session
 
-Connects this session to the local InSitue companion. The user
-picks an element in their app, types a description in the
-InSitue panel, clicks Send — and you receive the pick (file,
-line, component, screenshot) plus the description here, ready to
-act on.
+This is the operating manual the InSitue MCP loads at session
+start. On Claude Code it lands as the `/insitue:connect` slash
+command; on Claude Desktop the user has claude call the
+`start_session` tool to fetch the same content. Either way, the
+instructions below are how you behave for the rest of the chat.
+
+The user picks an element in their running app, types a
+description in the InSitue panel, clicks Send — and you receive
+the pick (file, line, component, screenshot) plus the
+description here, ready to act on.
 
 The companion auto-starts when this MCP server boots. You do
 not need to ask the user to run any extra commands.
 
+**Runtime note.** Where this manual says "use the Edit tool",
+that means:
+  - on **Claude Code** → the built-in Edit/Write/Read tools
+  - on **Claude Desktop** → the `apply_edit` / `write_file` /
+    `read_file` tools exposed by this same MCP server
+Either path is fine; pick whichever your runtime has.
+
 ## Your behaviour
 
 1. Call `mcp__insitue__list_recent_picks` once. If there are
@@ -53,8 +65,8 @@ not need to ask the user to run any extra commands.
    - Propose the edit with a clear diff in this chat. Wait for
      the user to say "yes" / "approve" / "go" before writing.
      Don't auto-apply.
-   - On approval, write with the Edit tool. Confirm what
-     changed.
+   - On approval, write with the Edit tool (Code) or
+     `mcp__insitue__apply_edit` (Desktop). Confirm what changed.
    - Loop back to `next_pick`.
 3. If `next_pick` returns `status: "timeout"`, the user simply
    hasn't picked anything yet. Stay quiet and call `next_pick`

package/dist/chunk-RF5Q55CG.js

@@ -0,0 +1,194 @@
+// src/diagnose.ts
+import { existsSync, readFileSync } from "fs";
+import { request as httpRequest } from "http";
+import { join } from "path";
+function readPkgVersion(projectDir, pkgName) {
+  const pkgJson = join(projectDir, "node_modules", pkgName, "package.json");
+  if (!existsSync(pkgJson)) return null;
+  try {
+    return JSON.parse(readFileSync(pkgJson, "utf8")).version ?? null;
+  } catch {
+    return null;
+  }
+}
+function readSession(projectDir) {
+  const file = join(projectDir, ".insitue", "session.json");
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function pokeCompanion(port) {
+  return new Promise((resolve2) => {
+    const req = httpRequest(
+      {
+        host: "127.0.0.1",
+        port,
+        path: "/insitue/handshake",
+        method: "GET",
+        timeout: 1500
+      },
+      (res) => {
+        res.resume();
+        resolve2({ alive: true, subscribers: null });
+      }
+    );
+    req.on("error", () => resolve2({ alive: false, subscribers: null }));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve2({ alive: false, subscribers: null });
+    });
+    req.end();
+  });
+}
+function detectSwcPluginConfigured(projectDir) {
+  for (const f of [
+    "next.config.mjs",
+    "next.config.js",
+    "next.config.ts",
+    "vite.config.ts",
+    "vite.config.js"
+  ]) {
+    const p = join(projectDir, f);
+    if (existsSync(p)) {
+      try {
+        const c = readFileSync(p, "utf8");
+        return c.includes("@insitue/swc-source-attr");
+      } catch {
+        return null;
+      }
+    }
+  }
+  return null;
+}
+async function diagnose(projectDir) {
+  const session = readSession(projectDir.dir);
+  const hasSessionFile = session !== null;
+  let companionReachable = false;
+  let companionPort = null;
+  let companionSubscribers = null;
+  if (session) {
+    const r = await pokeCompanion(session.port);
+    companionReachable = r.alive;
+    if (r.alive) companionPort = session.port;
+    companionSubscribers = r.subscribers;
+  }
+  const sdkVersion = readPkgVersion(projectDir.dir, "@insitue/sdk");
+  const swcPluginVersion = readPkgVersion(
+    projectDir.dir,
+    "@insitue/swc-source-attr"
+  );
+  const swcPluginConfigured = detectSwcPluginConfigured(projectDir.dir);
+  const recommendations = [];
+  if (!sdkVersion) {
+    recommendations.push(
+      "`@insitue/sdk` not installed in the project \u2014 `pnpm add -D @insitue/sdk`"
+    );
+  }
+  if (!swcPluginVersion) {
+    recommendations.push(
+      "`@insitue/swc-source-attr` not installed \u2014 exact source resolution will degrade. `pnpm add -D @insitue/swc-source-attr`"
+    );
+  }
+  if (swcPluginVersion && swcPluginConfigured === false) {
+    recommendations.push(
+      "`@insitue/swc-source-attr` installed but not wired into next.config / vite.config \u2014 see the SDK README for the snippet"
+    );
+  }
+  if (!hasSessionFile) {
+    recommendations.push(
+      "No `.insitue/session.json` yet \u2014 the companion hasn't run in this project. Start `pnpm dev` and the companion should auto-spawn when claude attaches."
+    );
+  } else if (!companionReachable) {
+    recommendations.push(
+      "Stale `.insitue/session.json` (companion not reachable). Delete the `.insitue/` directory and re-attach."
+    );
+  }
+  return {
+    projectDir,
+    hasSessionFile,
+    companionReachable,
+    companionPort,
+    companionSubscribers,
+    sdkVersion,
+    swcPluginVersion,
+    swcPluginConfigured,
+    recommendations
+  };
+}
+
+// src/project-dir.ts
+import { existsSync as existsSync2, realpathSync } from "fs";
+import { dirname, isAbsolute, join as join2, resolve } from "path";
+function readProjectDirArg(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--project-dir" && i + 1 < argv.length) return argv[i + 1];
+    if (a.startsWith("--project-dir=")) return a.slice("--project-dir=".length);
+  }
+  return null;
+}
+function walkUpFor(start, marker) {
+  let dir = resolve(start);
+  while (true) {
+    if (existsSync2(join2(dir, marker))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function realpathSafe(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+}
+function resolveProjectDir(argv = process.argv.slice(2), env = process.env) {
+  const fromArg = readProjectDirArg(argv);
+  if (fromArg) {
+    return { dir: realpathSafe(fromArg), source: "argv" };
+  }
+  if (env.INSITUE_PROJECT_DIR) {
+    return {
+      dir: realpathSafe(env.INSITUE_PROJECT_DIR),
+      source: "INSITUE_PROJECT_DIR"
+    };
+  }
+  if (env.CLAUDE_PROJECT_DIR) {
+    return {
+      dir: realpathSafe(env.CLAUDE_PROJECT_DIR),
+      source: "CLAUDE_PROJECT_DIR"
+    };
+  }
+  const cwd = process.cwd();
+  const sessionDir = walkUpFor(cwd, ".insitue");
+  if (sessionDir && existsSync2(join2(sessionDir, ".insitue", "session.json"))) {
+    return { dir: realpathSafe(sessionDir), source: "session-walk-up" };
+  }
+  const pkgDir = walkUpFor(cwd, "package.json");
+  if (pkgDir) {
+    return { dir: realpathSafe(pkgDir), source: "package-walk-up" };
+  }
+  return { dir: realpathSafe(cwd), source: "cwd" };
+}
+function isInsideProject(root, target) {
+  const r = realpathSafe(root);
+  let t;
+  try {
+    t = realpathSync(target);
+  } catch {
+    t = resolve(target);
+  }
+  if (!isAbsolute(r) || !isAbsolute(t)) return false;
+  const rWithSep = r.endsWith("/") ? r : r + "/";
+  return t === r || t.startsWith(rWithSep);
+}
+
+export {
+  diagnose,
+  resolveProjectDir,
+  isInsideProject
+};

package/dist/dispatcher.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+// src/dispatcher.ts
+var SUBCOMMANDS = /* @__PURE__ */ new Set(["setup", "diagnose", "help", "--help", "-h"]);
+var first = process.argv[2];
+if (first && SUBCOMMANDS.has(first)) {
+  await import("./setup-cli.js");
+} else {
+  await import("./mcp-server.js");
+}

package/dist/mcp-server.js

@@ -1,34 +1,184 @@
 #!/usr/bin/env node
+import {
+  diagnose,
+  isInsideProject,
+  resolveProjectDir
+} from "./chunk-RF5Q55CG.js";
 
 // src/mcp-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { spawn } from "child_process";
-import { existsSync, readFileSync } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
 import { request as httpRequest } from "http";
-import { dirname, join, resolve } from "path";
+import { dirname as dirname3, join as join3 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import WebSocket from "ws";
 import { z } from "zod";
+
+// src/file-tools.ts
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync
+} from "fs";
+import { dirname, isAbsolute, join } from "path";
+function resolveWithin(projectDir2, path) {
+  if (!path || typeof path !== "string") {
+    return {
+      ok: false,
+      result: { status: "error", message: "missing or invalid `path`" }
+    };
+  }
+  const abs = isAbsolute(path) ? path : join(projectDir2, path);
+  if (!isInsideProject(projectDir2, abs)) {
+    return {
+      ok: false,
+      result: {
+        status: "error",
+        message: `refused: \`${path}\` resolves outside the project dir (${projectDir2})`
+      }
+    };
+  }
+  return { ok: true, abs };
+}
+function readFileInProject(projectDir2, path, opts = {}) {
+  const resolved = resolveWithin(projectDir2, path);
+  if (!resolved.ok) return resolved.result;
+  if (!existsSync(resolved.abs)) {
+    return { status: "error", message: `file not found: ${path}` };
+  }
+  try {
+    const full = readFileSync(resolved.abs, "utf8");
+    if (opts.startLine == null && opts.endLine == null) {
+      return {
+        status: "ok",
+        content: full,
+        bytes: Buffer.byteLength(full, "utf8"),
+        message: `read ${path}`
+      };
+    }
+    const lines = full.split("\n");
+    const start = Math.max(1, opts.startLine ?? 1) - 1;
+    const end = Math.min(lines.length, opts.endLine ?? lines.length);
+    const slice = lines.slice(start, end).join("\n");
+    return {
+      status: "ok",
+      content: slice,
+      bytes: Buffer.byteLength(slice, "utf8"),
+      message: `read ${path} L${start + 1}-${end}`
+    };
+  } catch (err) {
+    return {
+      status: "error",
+      message: `read failed: ${err.message}`
+    };
+  }
+}
+function applyEditInProject(projectDir2, path, oldString, newString, opts = {}) {
+  const resolved = resolveWithin(projectDir2, path);
+  if (!resolved.ok) return resolved.result;
+  if (!existsSync(resolved.abs)) {
+    return { status: "error", message: `file not found: ${path}` };
+  }
+  if (oldString === newString) {
+    return {
+      status: "error",
+      message: "`oldString` and `newString` are identical \u2014 nothing to apply"
+    };
+  }
+  try {
+    const before = readFileSync(resolved.abs, "utf8");
+    if (!before.includes(oldString)) {
+      return {
+        status: "error",
+        message: "`oldString` not found in file \u2014 fetch the current content with read_file and retry with the exact match"
+      };
+    }
+    if (!opts.replaceAll) {
+      const first = before.indexOf(oldString);
+      const next = before.indexOf(oldString, first + oldString.length);
+      if (next !== -1) {
+        return {
+          status: "error",
+          message: "`oldString` matches multiple times \u2014 pass `replaceAll: true` or include more context to make the match unique"
+        };
+      }
+    }
+    const after = opts.replaceAll ? before.split(oldString).join(newString) : before.replace(oldString, newString);
+    writeFileSync(resolved.abs, after, "utf8");
+    const diffBytes = Buffer.byteLength(after, "utf8") - Buffer.byteLength(before, "utf8");
+    return {
+      status: "ok",
+      message: `applied edit to ${path} (${diffBytes >= 0 ? "+" : ""}${diffBytes} bytes)`,
+      bytes: Buffer.byteLength(after, "utf8")
+    };
+  } catch (err) {
+    return {
+      status: "error",
+      message: `edit failed: ${err.message}`
+    };
+  }
+}
+function writeFileInProject(projectDir2, path, content, opts = {}) {
+  const resolved = resolveWithin(projectDir2, path);
+  if (!resolved.ok) return resolved.result;
+  try {
+    if (opts.createParents) {
+      mkdirSync(dirname(resolved.abs), { recursive: true });
+    }
+    writeFileSync(resolved.abs, content, "utf8");
+    return {
+      status: "ok",
+      message: `wrote ${path} (${Buffer.byteLength(content, "utf8")} bytes)`,
+      bytes: Buffer.byteLength(content, "utf8")
+    };
+  } catch (err) {
+    return {
+      status: "error",
+      message: `write failed: ${err.message}`
+    };
+  }
+}
+
+// src/instructions.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname2, join as join2 } from "path";
+import { fileURLToPath } from "url";
+var cached = null;
+function loadInstructions() {
+  if (cached) return cached;
+  const here = dirname2(fileURLToPath(import.meta.url));
+  const candidates = [
+    join2(here, "..", "commands", "connect.md"),
+    join2(here, "commands", "connect.md")
+  ];
+  for (const p of candidates) {
+    try {
+      cached = readFileSync2(p, "utf8");
+      return cached;
+    } catch {
+    }
+  }
+  cached = "Call `mcp__insitue__next_pick` in a loop. Each ok-status pick has a `userNote` (the user's instruction) and a `source.file:line` (where to act). Propose an edit, ask for approval in this chat, then apply with `apply_edit` (or the runtime's native Edit tool).";
+  return cached;
+}
+
+// src/mcp-server.ts
 var MAX_BUFFERED_PICKS = 32;
 var NEXT_PICK_DEFAULT_TIMEOUT_MS = 25 * 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, ".insitue", "session.json");
-    if (existsSync(candidate)) {
-      try {
-        const session2 = JSON.parse(
-          readFileSync(candidate, "utf8")
-        );
-        return { dir, session: session2 };
-      } catch {
-        return null;
-      }
-    }
-    const parent = dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
+function findSession(projectDir2) {
+  const candidate = join3(projectDir2, ".insitue", "session.json");
+  if (!existsSync2(candidate)) return null;
+  try {
+    const session2 = JSON.parse(
+      readFileSync3(candidate, "utf8")
+    );
+    return { dir: projectDir2, session: session2 };
+  } catch {
+    return null;
   }
 }
 function summariseBundle(raw) {
@@ -76,13 +226,13 @@ var PickBuffer = class {
     if (this.picks.length) {
       return Promise.resolve(this.picks.shift());
     }
-    return new Promise((resolve2) => {
+    return new Promise((resolve) => {
       const timer = setTimeout(() => {
         const idx = this.waiters.findIndex((w) => w.timer === timer);
         if (idx >= 0) this.waiters.splice(idx, 1);
-        resolve2(null);
+        resolve(null);
       }, timeoutMs);
-      this.waiters.push({ resolve: resolve2, timer });
+      this.waiters.push({ resolve, timer });
     });
   }
   recent(limit) {
@@ -114,7 +264,7 @@ async function probeCompanion(session2) {
   } catch {
     return false;
   }
-  return new Promise((resolve2) => {
+  return new Promise((resolve) => {
     const req = httpRequest(
       {
         host: "127.0.0.1",
@@ -125,20 +275,20 @@ async function probeCompanion(session2) {
       },
       (res) => {
         res.resume();
-        resolve2(true);
+        resolve(true);
       }
     );
-    req.on("error", () => resolve2(false));
+    req.on("error", () => resolve(false));
     req.on("timeout", () => {
       req.destroy();
-      resolve2(false);
+      resolve(false);
     });
     req.end();
   });
 }
 var ownedChild = null;
-async function ensureCompanion() {
-  const existing = findSession();
+async function ensureCompanion(projectDir2) {
+  const existing = findSession(projectDir2);
   if (existing && await probeCompanion(existing.session)) {
     process.stderr.write(
       `[insitue-mcp] reusing companion at :${existing.session.port} (pid ${existing.session.pid})
@@ -147,13 +297,14 @@ async function ensureCompanion() {
     return existing.session;
   }
   process.stderr.write(
-    "[insitue-mcp] starting companion via `npx -y @insitue/companion@latest dev`\u2026\n"
+    `[insitue-mcp] starting companion via \`npx -y @insitue/companion@latest dev\` in ${projectDir2}\u2026
+`
   );
   ownedChild = spawn(
     "npx",
     ["-y", "@insitue/companion@latest", "dev"],
     {
-      cwd: process.cwd(),
+      cwd: projectDir2,
       stdio: ["ignore", "pipe", "pipe"],
       env: process.env
     }
@@ -172,8 +323,8 @@ async function ensureCompanion() {
     ownedChild = null;
   });
   const start = Date.now();
-  while (Date.now() - start < 5e3) {
-    const found = findSession();
+  while (Date.now() - start < 8e3) {
+    const found = findSession(projectDir2);
     if (found && await probeCompanion(found.session)) {
       return found.session;
     }
@@ -268,7 +419,12 @@ function connectToCompanion(session2) {
   ws.on("error", () => {
   });
 }
-var session = await ensureCompanion();
+var projectDir = resolveProjectDir();
+process.stderr.write(
+  `[insitue-mcp] project dir: ${projectDir.dir} (via ${projectDir.source})
+`
+);
+var session = await ensureCompanion(projectDir.dir);
 if (!session) {
   process.stderr.write(
     "[insitue-mcp] no companion available \u2014 `next_pick` will time out.\n"
@@ -282,7 +438,7 @@ function ensureSubscriberAttached() {
 }
 var server = new McpServer({
   name: "insitue",
-  version: "0.2.0"
+  version: "0.3.0"
 });
 server.registerTool(
   "next_pick",
@@ -336,4 +492,185 @@ server.registerTool(
     };
   }
 );
+server.registerTool(
+  "start_session",
+  {
+    description: "Returns the operating instructions for InSitue + current state (project dir, companion reachable, buffered pick count). On Claude Code you typically don't need this \u2014 the slash command `/insitue:connect` already loaded the instructions. On Claude Desktop there are no slash commands, so call this once at the start of every session before entering the next_pick loop.",
+    inputSchema: {}
+  },
+  async () => {
+    ensureSubscriberAttached();
+    const instructions = loadInstructions();
+    const buffered = buffer.recent(32).length;
+    const status = `
+
+---
+
+**Current state**
+
+- Project: \`${projectDir.dir}\` (resolved via ${projectDir.source})
+- Companion: ${session ? `reachable on port ${session.port}` : "NOT reachable"}
+- Buffered picks waiting: ${buffered}
+
+Begin the loop by calling \`list_recent_picks\` once, then loop on \`next_pick\`.`;
+    return {
+      content: [
+        { type: "text", text: instructions + status }
+      ]
+    };
+  }
+);
+server.registerTool(
+  "diagnose",
+  {
+    description: "Run a health check on the local InSitue setup \u2014 companion reachability, SDK install, SWC plugin install + wiring, session file freshness. Returns a structured report plus human-readable recommendations. Use when picks don't seem to be flowing.",
+    inputSchema: {}
+  },
+  async () => {
+    const report = await diagnose(projectDir);
+    return {
+      content: [
+        { type: "text", text: JSON.stringify(report, null, 2) }
+      ]
+    };
+  }
+);
+server.registerTool(
+  "read_file",
+  {
+    description: "Read a file from the resolved project directory. Paths are relative to the project root (or absolute, in which case they must still live inside the project). Optional `startLine`/`endLine` for partial reads. On Claude Code, prefer the built-in Read tool \u2014 this exists primarily for Claude Desktop, where no built-in file tools are available.",
+    inputSchema: {
+      path: z.string().describe("Project-relative or absolute path."),
+      startLine: z.number().int().positive().optional().describe("1-indexed start line (inclusive)."),
+      endLine: z.number().int().positive().optional().describe("1-indexed end line (inclusive).")
+    }
+  },
+  async ({ path, startLine, endLine }) => {
+    const opts = {};
+    if (startLine !== void 0) opts.startLine = startLine;
+    if (endLine !== void 0) opts.endLine = endLine;
+    const r = readFileInProject(projectDir.dir, path, opts);
+    return {
+      content: [
+        { type: "text", text: JSON.stringify(r) }
+      ]
+    };
+  }
+);
+server.registerTool(
+  "apply_edit",
+  {
+    description: "Apply a string-replacement edit to a file inside the project. `oldString` must occur exactly once in the file (otherwise pass `replaceAll: true`). Returns a status + brief summary. ALWAYS ask the user for explicit approval before calling this \u2014 InSitue's contract is human-in-the-loop on every write. On Claude Code, prefer the built-in Edit tool.",
+    inputSchema: {
+      path: z.string().describe("Project-relative or absolute path."),
+      oldString: z.string().describe("Exact text to replace."),
+      newString: z.string().describe("Replacement text."),
+      replaceAll: z.boolean().optional().describe(
+        "Replace every occurrence of `oldString` instead of refusing on ambiguity."
+      )
+    }
+  },
+  async ({ path, oldString, newString, replaceAll }) => {
+    const opts = {};
+    if (replaceAll !== void 0) opts.replaceAll = replaceAll;
+    const r = applyEditInProject(
+      projectDir.dir,
+      path,
+      oldString,
+      newString,
+      opts
+    );
+    return {
+      content: [
+        { type: "text", text: JSON.stringify(r) }
+      ]
+    };
+  }
+);
+server.registerTool(
+  "write_file",
+  {
+    description: "Write the full contents of a file inside the project. Use for new files or full rewrites where `apply_edit`'s string match isn't a good fit. ALWAYS ask the user for explicit approval before calling. On Claude Code, prefer the built-in Write tool.",
+    inputSchema: {
+      path: z.string().describe("Project-relative or absolute path."),
+      content: z.string().describe("Full file contents to write."),
+      createParents: z.boolean().optional().describe("Create parent directories if they don't exist.")
+    }
+  },
+  async ({ path, content, createParents }) => {
+    const opts = {};
+    if (createParents !== void 0) opts.createParents = createParents;
+    const r = writeFileInProject(projectDir.dir, path, content, opts);
+    return {
+      content: [
+        { type: "text", text: JSON.stringify(r) }
+      ]
+    };
+  }
+);
+server.registerPrompt(
+  "connect",
+  {
+    title: "Connect to InSitue",
+    description: "Loads the operating instructions and begins the pick \u2192 edit loop."
+  },
+  () => ({
+    messages: [
+      {
+        role: "user",
+        content: { type: "text", text: loadInstructions() }
+      }
+    ]
+  })
+);
+function readPkgFile(rel) {
+  const here = dirname3(fileURLToPath2(import.meta.url));
+  for (const base of [join3(here, ".."), here]) {
+    const p = join3(base, rel);
+    if (existsSync2(p)) {
+      try {
+        return readFileSync3(p, "utf8");
+      } catch {
+        return null;
+      }
+    }
+  }
+  return null;
+}
+server.registerResource(
+  "instructions",
+  "insitue://instructions",
+  {
+    title: "InSitue operating instructions",
+    description: "The same content that drives `/insitue:connect` on Code and `start_session` on Desktop.",
+    mimeType: "text/markdown"
+  },
+  async () => ({
+    contents: [
+      {
+        uri: "insitue://instructions",
+        mimeType: "text/markdown",
+        text: loadInstructions()
+      }
+    ]
+  })
+);
+server.registerResource(
+  "readme",
+  "insitue://readme",
+  {
+    title: "@insitue/claude-plugin README",
+    description: "Package overview, setup steps, and runtime notes.",
+    mimeType: "text/markdown"
+  },
+  async () => ({
+    contents: [
+      {
+        uri: "insitue://readme",
+        mimeType: "text/markdown",
+        text: readPkgFile("README.md") ?? "README not bundled \u2014 see https://github.com/InSitue/insitue/tree/main/packages/claude-plugin"
+      }
+    ]
+  })
+);
 await server.connect(new StdioServerTransport());

package/dist/setup-cli.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+import {
+  diagnose,
+  resolveProjectDir
+} from "./chunk-RF5Q55CG.js";
+
+// src/setup-cli.ts
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync
+} from "fs";
+import { basename, dirname, join, resolve } from "path";
+import { homedir, platform } from "os";
+function parseArgs(argv) {
+  const positional2 = [];
+  const flags2 = /* @__PURE__ */ new Map();
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) {
+      positional2.push(a);
+      continue;
+    }
+    const eq = a.indexOf("=");
+    if (eq !== -1) {
+      flags2.set(a.slice(2, eq), a.slice(eq + 1));
+    } else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+      flags2.set(a.slice(2), argv[++i]);
+    } else {
+      flags2.set(a.slice(2), true);
+    }
+  }
+  return { positional: positional2, flags: flags2 };
+}
+function desktopConfigPath() {
+  const home = homedir();
+  switch (platform()) {
+    case "darwin":
+      return join(
+        home,
+        "Library",
+        "Application Support",
+        "Claude",
+        "claude_desktop_config.json"
+      );
+    case "win32":
+      return join(
+        process.env.APPDATA ?? join(home, "AppData", "Roaming"),
+        "Claude",
+        "claude_desktop_config.json"
+      );
+    default:
+      return join(
+        process.env.XDG_CONFIG_HOME ?? join(home, ".config"),
+        "Claude",
+        "claude_desktop_config.json"
+      );
+  }
+}
+function makeEntryName(projectDir, explicit) {
+  if (explicit) return explicit;
+  const base = basename(projectDir).toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+  return `insitue-${base || "project"}`;
+}
+function buildEntry(projectDir) {
+  return {
+    command: "npx",
+    args: ["-y", "@insitue/claude-plugin@latest"],
+    env: {
+      INSITUE_PROJECT_DIR: projectDir
+    }
+  };
+}
+function readDesktopConfig(path) {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new Error(
+      `Couldn't parse existing config at ${path}: ${err.message}. Fix the JSON manually and re-run.`
+    );
+  }
+}
+function writeDesktopConfig(path, cfg) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+function backupConfig(path) {
+  if (!existsSync(path)) return null;
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const backup = `${path}.insitue-backup-${stamp}`;
+  copyFileSync(path, backup);
+  return backup;
+}
+async function cmdSetup(flags2) {
+  const projectFlag = flags2.get("project");
+  const projectDir = resolve(
+    typeof projectFlag === "string" ? projectFlag : process.cwd()
+  );
+  if (!existsSync(projectDir)) {
+    process.stderr.write(`error: project dir doesn't exist: ${projectDir}
+`);
+    return 1;
+  }
+  const wantDesktop = flags2.has("desktop") || flags2.has("both");
+  const wantCode = flags2.has("code") || flags2.has("both");
+  const wantInteractive = !flags2.has("desktop") && !flags2.has("code") && !flags2.has("both");
+  const name = typeof flags2.get("name") === "string" ? flags2.get("name") : makeEntryName(projectDir);
+  const entry = buildEntry(projectDir);
+  const dryRun = flags2.has("dry-run");
+  if (wantInteractive) {
+    process.stdout.write(
+      `InSitue setup
+\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+Project: ${projectDir}
+Entry name: ${name}
+
+Pass one of:
+  --desktop       Wire into Claude Desktop
+  --code          Print the Claude Code marketplace install hint
+  --both          Both runtimes
+
+Example:
+  npx @insitue/claude-plugin setup --desktop --project=${projectDir}
+`
+    );
+    return 0;
+  }
+  if (wantCode) {
+    process.stdout.write(
+      "\nClaude Code setup\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nInside `claude`, run:\n\n  /plugin marketplace add InSitue/insitue\n  /plugin install insitue@insitue-plugins\n\nThen `/insitue:connect` to start the loop. No further config\nneeded \u2014 claude provides ${CLAUDE_PROJECT_DIR} automatically.\n"
+    );
+  }
+  if (wantDesktop) {
+    const cfgPath = desktopConfigPath();
+    process.stdout.write(
+      `
+Claude Desktop setup
+\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+Config file: ${cfgPath}
+Entry name:  ${name}
+Project:     ${projectDir}
+`
+    );
+    const cfg = readDesktopConfig(cfgPath);
+    const current = cfg.mcpServers?.[name];
+    const same = current && JSON.stringify(current) === JSON.stringify(entry);
+    if (same) {
+      process.stdout.write(
+        "\u2713 Already wired correctly \u2014 no changes needed.\n"
+      );
+    } else if (dryRun) {
+      process.stdout.write(
+        `
+[dry-run] Would write entry:
+  "${name}": ${JSON.stringify(entry, null, 2).replace(/\n/g, "\n  ")}
+`
+      );
+    } else {
+      const backup = backupConfig(cfgPath);
+      const next = { ...cfg };
+      next.mcpServers = { ...cfg.mcpServers ?? {}, [name]: entry };
+      writeDesktopConfig(cfgPath, next);
+      process.stdout.write(
+        (backup ? `\u2713 Backed up existing config \u2192 ${backup}
+` : "\u2713 Created new config (no existing file).\n") + `\u2713 Wrote entry "${name}".
+
+Restart Claude Desktop, then start a new chat and tell
+claude: "Use the InSitue MCP \u2014 call \`start_session\` and
+follow the instructions it returns."
+`
+      );
+    }
+  }
+  process.stdout.write("\n");
+  return 0;
+}
+async function cmdDiagnose(flags2) {
+  const projectFlag = flags2.get("project");
+  const argv = typeof projectFlag === "string" ? ["--project-dir", projectFlag] : [];
+  const projectDir = resolveProjectDir(argv);
+  const report = await diagnose(projectDir);
+  const tick = (b) => b ? "\u2713" : "\u2717";
+  const lines = [
+    "InSitue diagnostics",
+    "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
+    `Project:    ${report.projectDir.dir} (via ${report.projectDir.source})`,
+    `Session:    ${tick(report.hasSessionFile)} .insitue/session.json ${report.hasSessionFile ? "exists" : "missing"}`,
+    `Companion:  ${tick(report.companionReachable)} ${report.companionReachable ? `reachable on port ${report.companionPort}` : "not reachable"}`,
+    `@insitue/sdk:              ${report.sdkVersion ?? "(not installed)"}`,
+    `@insitue/swc-source-attr:  ${report.swcPluginVersion ?? "(not installed)"}`,
+    `SWC plugin configured:     ${report.swcPluginConfigured == null ? "(no next/vite config found)" : report.swcPluginConfigured ? "yes" : "no"}`
+  ];
+  if (report.recommendations.length) {
+    lines.push("", "Recommendations:");
+    for (const r of report.recommendations) lines.push(`  \xB7 ${r}`);
+  } else {
+    lines.push("", "No recommendations \u2014 everything looks healthy.");
+  }
+  process.stdout.write(lines.join("\n") + "\n");
+  return 0;
+}
+function cmdHelp() {
+  process.stdout.write(
+    "Usage: insitue <command> [flags]\n\nCommands:\n  setup       Wire the InSitue MCP into Claude Desktop / Code\n  diagnose    Health-check the local InSitue setup\n  help        Show this message\n\nFlags (setup):\n  --desktop                  Configure Claude Desktop\n  --code                     Print the Claude Code install hint\n  --both                     Configure both\n  --project=PATH             Project directory (default: cwd)\n  --name=NAME                Desktop MCP entry name (default: insitue-<dirname>)\n  --dry-run                  Show what would change without writing\n\nFlags (diagnose):\n  --project=PATH             Project directory (default: walk-up from cwd)\n"
+  );
+  return 0;
+}
+var { positional, flags } = parseArgs(process.argv.slice(2));
+var sub = positional[0] ?? "help";
+try {
+  let code;
+  switch (sub) {
+    case "setup":
+      code = await cmdSetup(flags);
+      break;
+    case "diagnose":
+      code = await cmdDiagnose(flags);
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+      code = cmdHelp();
+      break;
+    default:
+      process.stderr.write(`unknown command: ${sub}
+`);
+      cmdHelp();
+      code = 2;
+  }
+  process.exit(code);
+} catch (err) {
+  process.stderr.write(`error: ${err.message}
+`);
+  process.exit(1);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@insitue/claude-plugin",
-  "version": "0.3.3",
-  "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.",
+  "version": "0.4.1",
+  "description": "Drive Claude (Code AND Desktop) from the InSitue browser overlay — pick an element in your app, claude reads the file and proposes the edit.",
   "license": "MIT",
   "type": "module",
   "files": [
@@ -14,7 +14,7 @@
     ".": "./dist/mcp-server.js"
   },
   "bin": {
-    "insitue-mcp": "./dist/mcp-server.js"
+    "insitue-claude-plugin": "./dist/dispatcher.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -30,8 +30,8 @@
     "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",
+    "build": "tsup src/dispatcher.ts src/mcp-server.ts src/setup-cli.ts --format esm --clean --external @modelcontextprotocol/sdk --external ws --external zod",
+    "dev": "tsup src/dispatcher.ts src/mcp-server.ts src/setup-cli.ts --format esm --watch --external @modelcontextprotocol/sdk --external ws --external zod",
     "typecheck": "tsc --noEmit",
     "lint": "tsc --noEmit"
   }