@insitue/claude-plugin 0.6.3 → 0.7.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "insitue",
-  "version": "0.5.3",
+  "version": "0.6.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": {
@@ -11,5 +11,10 @@
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}"
     }
-  }
+  },
+  "channels": [
+    {
+      "server": "insitue"
+    }
+  ]
 }

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @insitue/claude-plugin
 
+## 0.7.0
+
+- **Live picks without blocking the chat (channels, opt-in preview).** The MCP server now also PUSHES each pick as a Claude Code channel event (`notifications/claude/channel`). Start your session with `claude --dangerously-load-development-channels --channels plugin:insitue` and picks wake the idle agent instead of you waiting on a poll — the chat stays free for conversation the rest of the time. Plain `claude` + `/insitue:connect` is unchanged (8s poll fallback). The agent de-dupes by pick id, so the push + poll paths never double-handle a pick. Channels are a Claude Code research-preview feature (CLI-only); the flag is required during the preview.
+
 ## 0.6.3
 
 - **Responsive watch — interject without cancelling.** The `next_pick` long-poll is now 8s (was 25s). While the watch is running you can just type a message: Claude Code queues it and delivers it the moment the poll returns (≤~8s), so you no longer have to cancel the watch to ask a question. The connect instructions now make clear the watch never needs to be cancelled to talk — Claude answers and resumes watching.

package/README.md

@@ -177,6 +177,35 @@ before writing. After it writes, your dev server's HMR picks up
 the change and you see it live in the browser. Pick the next
 thing.
 
+### Live picks without blocking the chat (channels, preview)
+
+By default the agent polls `next_pick` every ~8 s — the chat is
+technically available between polls, but the polling loop runs
+continuously in the background.
+
+As an opt-in upgrade (Claude Code CLI only, research preview),
+you can have picks **pushed** directly into the session so the
+chat stays completely free between picks:
+
+```bash
+claude --dangerously-load-development-channels --channels plugin:insitue
+```
+
+With this flag, every pick the user sends from the browser wakes
+Claude immediately via a channel notification — no polling needed,
+and the chat is genuinely idle between picks. Claude still buffers
+picks for `next_pick` in parallel, so a stale session or a missing
+channel listener falls back to the normal poll automatically.
+
+**Notes:**
+- This is a **Claude Code research-preview** feature. The flag
+  `--dangerously-load-development-channels` is required during the
+  preview period and may change or be renamed in a future release.
+- It works only with the CLI (`claude`), not Claude Desktop.
+- The standard `/insitue:connect` workflow (plain `claude`, no
+  extra flags) continues to work exactly as before via polling —
+  channels are purely an opt-in upgrade, not a requirement.
+
 ---
 
 ## What gets shipped to claude

package/commands/connect.md

@@ -25,6 +25,40 @@ that means:
     `read_file` tools exposed by this same MCP server
 Either path is fine; pick whichever your runtime has.
 
+## Pick delivery modes and idempotency
+
+Picks can reach you in one of two ways depending on how `claude`
+was started. **Act on each pick `id` exactly once** regardless of
+which path delivered it — the server always does both, so
+double-delivery is possible and you must de-dupe by `id`.
+
+### Push mode (channels — opt-in, Claude Code only)
+
+If the user started Claude Code with channel support
+(`claude --dangerously-load-development-channels --channels plugin:insitue`),
+picks are PUSHED into this session as
+`<channel source="insitue">…</channel>` events. Each event
+contains the pick's `id`, `userNote`, `source file:line`,
+`confidence`, and URL — everything you need to act.
+
+**In push mode you do NOT need to loop `next_pick`.** Stay idle
+between picks so the user can chat freely. Each pushed pick wakes
+you; handle it exactly like a `next_pick` pick (echo the request,
+read the file, propose the edit, etc.), then go idle again.
+
+### Poll mode (plain `claude` — default)
+
+If no `<channel>` pick events arrive, you are in poll mode. Loop
+`next_pick` as described in §2 below (default 8 s timeout). This
+is the same behaviour as before channels existed and requires no
+extra flags.
+
+### Don't double-handle
+
+If the same pick `id` arrives both via a channel event AND via
+`next_pick`, act on it exactly once. Keep a set of handled ids in
+your context and skip any id you've already processed.
+
 ## Your behaviour
 
 1. Call `mcp__insitue__list_recent_picks` once. If there are

package/dist/mcp-server.js

@@ -501,6 +501,25 @@ function connectToCompanion(s) {
               `[insitue] \u{1F4E5} pick received \u2014 "${note}" @ ${where}
 `
             );
+            try {
+              const channelContent = `InSitue pick ready (id: ${summary.id})
+Note: ${summary.userNote ?? "(no description)"}
+Source: ${summary.source ? `${summary.source.file}:${summary.source.line ?? "?"}` : "(unknown)"}
+Confidence: ${summary.confidence}
+` + (summary.url ? `URL: ${summary.url}
+` : "");
+              void server.server.notification(
+                {
+                  method: "notifications/claude/channel",
+                  params: {
+                    content: channelContent,
+                    meta: { pick_id: summary.id }
+                  }
+                }
+              ).catch(() => {
+              });
+            } catch {
+            }
           } catch (err) {
             process.stderr.write(
               `[insitue-mcp] dropped malformed pick: ${err.message}
@@ -590,10 +609,21 @@ function endSession() {
   session = null;
   return { closedWs, killedCompanion, removedSessionFile };
 }
-var server = new McpServer({
-  name: "insitue",
-  version: readPackageVersion()
-});
+var server = new McpServer(
+  {
+    name: "insitue",
+    version: readPackageVersion()
+  },
+  {
+    capabilities: {
+      // Declare the Claude Code "channel" experimental capability so the
+      // MCP server is permitted to emit notifications/claude/channel events.
+      // Claude Code checks for this key during its research-preview channel
+      // handshake; without it the push notification is silently dropped.
+      experimental: { "claude/channel": {} }
+    }
+  }
+);
 server.registerTool(
   "next_pick",
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insitue/claude-plugin",
-  "version": "0.6.3",
+  "version": "0.7.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.",
   "keywords": [
     "insitue",