@insitue/claude-plugin 0.7.5 → 0.7.7

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "insitue",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "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/CHANGELOG.md

@@ -1,12 +1,21 @@
 # @insitue/claude-plugin
 
+## 0.7.7
+
+- **New `/insitue:watch` — hands-free pick mode.** Acts on every browser pick the instant you make it (press Esc once to chat; the watch resumes after). `/insitue:connect` stays the responsive default (never blocks your typing; a pick is grabbed on your next message). Pick whichever fits — on a poll you can have instant OR non-blocking, not both.
+- **Channels demoted to a footnote.** The connect message and README now point you at `/insitue:watch` for hands-free instead of the per-launch `--dangerously-load-development-channels` flag (which can't be enabled once-and-for-all by individual users). Channels remain documented as the future zero-friction push path.
+
+## 0.7.6
+
+- **Fix the channels command (again) — use ONE flag.** `--dangerously-load-development-channels` is itself variadic and takes the channel entry directly; passing `--channels` after it makes the dev flag swallow `--channels` as an (invalid) entry ("entries must be tagged"). Correct form: `claude --dangerously-load-development-channels plugin:insitue@insitue-plugins`. (`--channels` alone is the separate allowlisted-plugin path.)
+
 ## 0.7.5
 
 - **Fix the channels command — it must be tagged with the marketplace.** The flag is `--channels plugin:insitue@insitue-plugins` (not `plugin:insitue`, which errored with "entries must be tagged"). Corrected in the `/insitue:connect` tip, the README, and the push-mode docs. Also synced the marketplace listing version.
 
 ## 0.7.4
 
-- **`/insitue:connect` no longer blocks the session.** In poll mode the agent silently re-looped `next_pick` forever, freezing the chat (queued messages never processed). It now polls once then hands control back, drains buffered picks on your next message, and points you at channel mode (`--dangerously-load-development-channels --channels plugin:insitue@insitue-plugins`) for truly hands-free background picks.
+- **`/insitue:connect` no longer blocks the session.** In poll mode the agent silently re-looped `next_pick` forever, freezing the chat (queued messages never processed). It now polls once then hands control back, drains buffered picks on your next message, and points you at channel mode (`--dangerously-load-development-channels plugin:insitue@insitue-plugins`) for truly hands-free background picks.
 - **Brand the sign-in success page.** The loopback login success page uses the brand purple gradient heading instead of the off-brand green.
 
 ## 0.7.3
@@ -25,7 +34,7 @@
 
 ## 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@insitue-plugins` 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.
+- **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 plugin:insitue@insitue-plugins` 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
 

package/README.md

@@ -47,15 +47,22 @@ auto-start the InSitue companion process in the background of
 your `claude` session — no separate terminal to babysit. The
 slash command `/insitue:connect` enters the loop.
 
-The plugin ships four slash commands:
+The plugin ships five slash commands:
 
 | Command | What it does |
 |---|---|
-| `/insitue:connect` | Enter the pick→edit loop — receive browser picks and act on them. |
+| `/insitue:connect` | Enter the pick→edit loop (responsive): act on picks, never blocks your typing — a pick is grabbed on your next message. |
+| `/insitue:watch` | Hands-free pick mode (proactive): act on every pick the instant you make it. Press Esc once to chat; the watch resumes after. |
 | `/insitue:disconnect` | Leave the loop: close the WS, stop receiving picks, and kill the companion the plugin spawned. |
 | `/insitue:login` | Browser sign-in (PKCE) to InSitue Cloud, then auto-link this repo to its project. |
 | `/insitue:logout` | Revoke the token server-side and clear local credentials. |
 
+**Two watch modes, because polling forces a trade-off.** `/insitue:connect`
+keeps your chat fully responsive but a pick waits for your next message;
+`/insitue:watch` acts on picks instantly but you press Esc to interject. You
+can't have both on a poll — only *push* (channels, below) gives instant +
+non-blocking, and that's still a research preview.
+
 ### 1B. Claude Desktop — one-command setup
 
 Claude Desktop doesn't have a plugin marketplace, but it does
@@ -186,35 +193,37 @@ 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)
+### Hands-free picks — `/insitue:watch` now, channels later
 
-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.
+By default (`/insitue:connect`) the chat stays fully responsive and a pick
+is grabbed on your next message. For a heads-down session where you want
+every pick acted on the instant you make it, run **`/insitue:watch`** (press
+Esc once to chat; the watch resumes after).
 
-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:
+Neither polling mode is *both* instant and non-blocking — that needs picks
+**pushed** into an idle session, which Claude Code supports today only as a
+research-preview "channel":
 
 ```bash
-claude --dangerously-load-development-channels --channels plugin:insitue@insitue-plugins
+claude --dangerously-load-development-channels plugin:insitue@insitue-plugins
 ```
 
-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.
+With that flag, every browser pick wakes Claude immediately via a channel
+notification — instant *and* the chat stays free. Claude still buffers picks
+for `next_pick` in parallel, so a missing channel listener falls back to
+polling 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.
-- **Dropping the flag:** on Team/Enterprise, an admin can add `insitue`
-  to the `allowedChannelPlugins` org policy — then the channel runs with
-  just `claude --channels plugin:insitue@insitue-plugins` (no dangerous flag). Once
-  channels leave research preview / the plugin is on Anthropic's default
-  allowlist, the flag won't be needed at all.
+- Channels are a **Claude Code research preview**, and the flag must be
+  passed **every launch** — there's no settings-level enable for individual
+  users yet, so it isn't an "opt in once" experience. Until it graduates,
+  `/insitue:watch` is the no-flag way to get hands-free picks.
+- The flag `--dangerously-load-development-channels` may change or be renamed
+  during the preview.
+- **Org allowlist:** on Team/Enterprise an admin can add `insitue` to the
+  `allowedChannelPlugins` policy — then it runs with just
+  `claude --channels plugin:insitue@insitue-plugins`. Once channels leave
+  research preview, no flag will be needed at all.
 - 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 —

package/commands/connect.md

@@ -35,7 +35,7 @@ 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@insitue-plugins`),
+(`claude --dangerously-load-development-channels plugin:insitue@insitue-plugins`),
 picks are PUSHED into this session as
 `<channel source="insitue">…</channel>` events. Each event
 contains the pick's `id`, `userNote`, `source file:line`,
@@ -66,13 +66,13 @@ your context and skip any id you've already processed.
    ("you picked X but haven't sent a description yet — make sure
    to click Send in the InSitue panel"). Otherwise say:
 
-   > Connected. Pick an element in the browser and I'll act on it
-   > here. You can also just type to ask me anything — I'll answer
-   > right away, then keep watching.
+   > Connected. Pick an element in the browser, then send me any
+   > message and I'll act on it — or just type to ask me anything,
+   > anytime. I never block your typing.
    >
-   > Tip: for hands-free background picks (so I act the moment you
-   > pick, without you waiting on me), relaunch with
-   > `claude --dangerously-load-development-channels --channels plugin:insitue@insitue-plugins`.
+   > Tip: for a hands-free session where I act on every pick the
+   > instant you make it (no need to message me first), run
+   > `/insitue:watch`.
 
 2. **Watch for a pick — ONE poll, then hand control back.** Call
    `mcp__insitue__next_pick` (it long-polls ~8s).
@@ -87,9 +87,10 @@ your context and skip any id you've already processed.
      > grab whatever you picked.
 
      Then wait for the user. You resume watching on their next message
-     (step 3). In plain poll mode you catch picks when the user next
-     interacts — for truly hands-free push *between* messages, they need
-     channel mode (the tip in step 1).
+     (step 3). In this mode you catch picks when the user next interacts.
+     If they want every pick acted on the instant it's made (hands-free),
+     tell them to run `/insitue:watch` (proactive mode; Esc to chat). True
+     push *between* messages also works if they started in channel mode.
    - On `status: "ok"` (a pick arrived):
    - **Always echo the prompt back first.** Before any action,
      diff, or follow-up question, lead with:

package/commands/watch.md

@@ -0,0 +1,73 @@
+---
+description: Hands-free InSitue pick mode — Claude watches and acts on every browser pick the instant you make it (press Esc to chat).
+---
+
+# /insitue:watch
+
+Proactive pick mode. Unlike `/insitue:connect` — which hands control
+back after each short poll so you can type freely, and grabs your pick
+on your next message — this **stays watching**: Claude long-polls for
+picks and acts on each one the moment you make it, truly hands-free.
+
+The trade-off (a Claude Code constraint, not a choice): while a poll is
+running, the only way to send a message is to press **Esc** once. Claude
+answers, then resumes watching. So:
+
+- Use **`/insitue:watch`** for heads-down sessions — you're clicking
+  through the UI and want every pick handled with zero nudging.
+- Use **`/insitue:connect`** for mixed work — you chat as much as you
+  pick and never want to hit Esc (a pick waits for your next message).
+
+## Your behaviour
+
+1. **Attach + announce.** Call `mcp__insitue__list_recent_picks` once —
+   this attaches the subscriber, so the browser launcher turns purple.
+   Handle any already-buffered picks (step 2 rules). Then say, in one
+   line:
+
+   > 👀 Hands-free watch on — pick anywhere in the browser and I'll act
+   > on it immediately. Press **Esc** once if you want to ask me
+   > something; I'll pick the watch back up after.
+
+2. **Watch loop.** Call `mcp__insitue__next_pick` with a long
+   `timeout_ms` (`600000` — 10 min; a pick still returns the instant
+   it's made, the timeout is just a heartbeat).
+   - On `status: "ok"`: handle the pick using the **same rules as
+     `/insitue:connect`** — echo the prompt verbatim FIRST
+     (`> **You asked:** <pick.userNote>` + `source.file:line` +
+     `confidence`), read the file around `source.line`, warn if
+     `confidence` is `approximate`, refuse `selector-only`, propose a
+     diff, wait for explicit approval, then write with the Edit tool
+     (Code) / `mcp__insitue__apply_edit` (Desktop). Then call
+     `next_pick` again — keep watching.
+   - On `status: "timeout"`: just call `next_pick` again. **Do not
+     narrate the loop** ("still watching…"). The browser prints
+     `[insitue] 📥 pick received` itself when a pick lands.
+
+3. **When the user interjects** (they pressed Esc and typed): answer
+   them fully and do whatever they ask, then resume the watch loop by
+   calling `next_pick` again. Their message is always the priority —
+   never tell them to cancel or re-run anything to talk to you.
+
+4. **Exit.** When the user says "stop watching", "done", "stop", "quit",
+   or runs `/insitue:disconnect`, call `mcp__insitue__end_session` once,
+   confirm in a single line, and stop calling `next_pick`. If their
+   "stop" is clearly scoped to the current task (not ending InSitue),
+   keep watching — read the room.
+
+## Guardrails
+
+Same as `/insitue:connect`: one pick = one approved edit, never
+auto-apply, trust `pick.userNote` as the instruction (it's a change
+request, not a discussion), cite the file + lines you read, and defer
+broad refactors with a follow-up question rather than bundling silently.
+
+## Why two modes?
+
+Browser picks reach Claude by polling the companion (`next_pick`). A
+running poll can't be interrupted except with Esc, and Claude Code only
+delivers a queued message when a turn ends — so a watch is either
+proactive (this command, Esc to talk) or non-blocking (`/insitue:connect`,
+pick waits for your next message), not both. When Claude Code Channels
+leave research preview, InSitue will push picks to an idle session and
+this trade-off disappears.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insitue/claude-plugin",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "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",