@insitue/claude-plugin 0.6.2 → 0.7.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "insitue",
-  "version": "0.5.2",
+  "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,13 @@
 # @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.
+
 ## 0.6.2
 
 - **Echo the request before fixing.** The cloud-issue instructions (connect.md + the `claim_cloud_issue` tool) now require Claude to print the exact request verbatim ("Fixing locally: …") before any analysis or edits, so you always see what it's about to act on.

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,19 +25,57 @@ 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
    any picks the user made before you attached, summarise them
    ("you picked X but haven't sent a description yet — make sure
    to click Send in the InSitue panel"). Otherwise just say
-   "Connected. Pick something in the browser when you're ready."
+   "Connected — pick something in the browser when you're ready.
+   You can also just type to ask me anything anytime; I'll answer
+   and keep watching, no need to cancel."
 2. Enter the loop: call `mcp__insitue__next_pick`. It long-polls
-   (~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"`:
+   (~8s — deliberately short. The user can type at ANY time without
+   cancelling: Claude Code queues their message and delivers it the
+   moment this call returns, so a short poll means they wait at most
+   ~8s to reach you and never need to hit Esc). When it returns with
+   `status: "timeout"` **and the user hasn't said anything**, 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:
 
@@ -73,10 +111,14 @@ Either path is fine; pick whichever your runtime has.
    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`.
+   confirmation, not your narration. **The user never has to cancel
+   the watch to talk to you.** When a message from the user arrives
+   while you're watching (it queues during the poll and lands the
+   moment `next_pick` returns), STOP looping, answer it fully, and do
+   whatever they ask — then resume the watch by calling `next_pick`
+   again. Their message is the priority; the watch waits for them, not
+   the other way around. Never tell the user to cancel or re-run
+   `/insitue:connect` just to ask a question.
 4. **End the session properly.** When the user says "stop",
    "done", "quit", "thanks", "exit", "disconnect", "stop
    insitue", or anything else that clearly ends the InSitue

package/dist/mcp-server.js

@@ -204,7 +204,7 @@ function readPackageVersion() {
   return "unknown";
 }
 var MAX_BUFFERED_PICKS = 32;
-var NEXT_PICK_DEFAULT_TIMEOUT_MS = 25 * 1e3;
+var NEXT_PICK_DEFAULT_TIMEOUT_MS = 8 * 1e3;
 var NEXT_PICK_MAX_TIMEOUT_MS = 30 * 60 * 1e3;
 function findSession(projectDir2) {
   const candidate = join3(projectDir2, ".insitue", "session.json");
@@ -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.2",
+  "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",