@insitue/claude-plugin 0.3.2 → 0.4.0

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
@@ -21,7 +33,11 @@ not need to ask the user to run any extra commands.
    to click Send in the InSitue panel"). Otherwise just say
    "Connected. Pick something in the browser when you're ready."
 2. Enter the loop: call `mcp__insitue__next_pick`. It long-polls
-   (~5 min default). When it returns with `status: "ok"`:
+   (~25s default — short on purpose so the chat stays responsive
+   to other questions the user might type while you wait). When
+   it returns with `status: "timeout"`, **call it again immediately
+   without announcing it** — the timeout is just a heartbeat, not
+   news. When it returns with `status: "ok"`:
    - **Always echo the prompt back first.** Before any action,
      diff, or follow-up question, lead with:
 
@@ -49,12 +65,18 @@ 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`
-   again.
+   again. **Do not narrate the loop** — no "still waiting…", no
+   "polling again…". The user sees `[insitue] 📥 pick received`
+   on stderr the moment their pick lands; that's the
+   confirmation, not your narration. If the user types another
+   question while you're between calls, answer it first (since
+   the chat is responsive), then resume the loop with
+   `next_pick`.
 4. If a pick comes back with `target` starting with
    `[insitue]` (e.g. "companion disconnected"), tell the user
    what happened in one sentence and call `next_pick` again —

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/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";
-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, ".insitue", "session.json");
-    if (existsSync(candidate)) {
-      try {
-        const session2 = JSON.parse(
-          readFileSync(candidate, "utf8")
-        );
-        return { dir, session: session2 };
-      } catch {
-        return null;
+
+// 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 });
     }
-    const parent = dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
+    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(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) {
@@ -54,7 +204,8 @@ function summariseBundle(raw) {
     selector: t?.selector ?? null,
     userNote: raw.bundle.userNote ?? null,
     url: raw.bundle.runtime?.url ?? null,
-    componentStack
+    componentStack,
+    ...t?.cmsSource ? { cmsSource: t.cmsSource } : {}
   };
 }
 var PickBuffer = class {
@@ -75,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) {
@@ -113,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",
@@ -124,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})
@@ -146,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
     }
@@ -171,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;
     }
@@ -239,8 +391,15 @@ function connectToCompanion(session2) {
       }
       if (tag === "broadcast-capture") {
         try {
-          buffer.push(
-            summariseBundle(m)
+          const summary = summariseBundle(
+            m
+          );
+          buffer.push(summary);
+          const note = summary.userNote ? summary.userNote.length > 60 ? `${summary.userNote.slice(0, 57)}\u2026` : summary.userNote : "(no description)";
+          const where = summary.source ? `${summary.source.file}:${summary.source.line}` : summary.target;
+          process.stderr.write(
+            `[insitue] \u{1F4E5} pick received \u2014 "${note}" @ ${where}
+`
           );
         } catch (err) {
           process.stderr.write(
@@ -260,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"
@@ -274,7 +438,7 @@ function ensureSubscriberAttached() {
 }
 var server = new McpServer({
   name: "insitue",
-  version: "0.2.0"
+  version: "0.3.0"
 });
 server.registerTool(
   "next_pick",
@@ -328,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.2",
-  "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.0",
+  "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,8 @@
     ".": "./dist/mcp-server.js"
   },
   "bin": {
-    "insitue-mcp": "./dist/mcp-server.js"
+    "insitue-mcp": "./dist/mcp-server.js",
+    "insitue": "./dist/setup-cli.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -30,8 +31,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/mcp-server.ts src/setup-cli.ts --format esm --clean --external @modelcontextprotocol/sdk --external ws --external zod",
+    "dev": "tsup src/mcp-server.ts src/setup-cli.ts --format esm --watch --external @modelcontextprotocol/sdk --external ws --external zod",
     "typecheck": "tsc --noEmit",
     "lint": "tsc --noEmit"
   }