@insitue/claude-plugin 0.7.3 → 0.7.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "insitue",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "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,5 +1,10 @@
 # @insitue/claude-plugin
 
+## 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`) 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
 
 - **Device-flow login for SSH/remote.** `/insitue:login` (+ `authenticate` tool) auto-detects an SSH session and uses a device flow: shows a verification URL + pairing code to approve in any browser; `complete_authentication` polls for the token. `login --device` forces it. Loopback stays the default locally.

package/README.md

@@ -47,6 +47,15 @@ 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:
+
+| Command | What it does |
+|---|---|
+| `/insitue:connect` | Enter the pick→edit loop — receive browser picks and act on them. |
+| `/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. |
+
 ### 1B. Claude Desktop — one-command setup
 
 Claude Desktop doesn't have a plugin marketplace, but it does
@@ -275,8 +284,8 @@ If your project uses InSitue Cloud, bug reports captured in production land in y
 
 ### Prerequisites
 
-1. **Authenticate:** run `insitue login` (from the `@insitue/companion` CLI). This stores a token at `~/.insitue/auth.json`. Get the token at <https://app.insitue.com/app/settings/developer>.
-2. **Link your project:** run `insitue link <projectId>` in your project root. The tools read the linked project from `.insitue/project.json`.
+1. **Authenticate:** run `insitue login` (from the `@insitue/companion` CLI), or `/insitue:login` inside Claude Code. Bare `insitue login` is a tokenless **browser** sign-in via PKCE — it opens your browser, prints an authorize URL + a short code to confirm, and on success prints `✓ Signed in as <login>`. Credentials are saved to `~/.insitue/auth.json`. A token minted this way from inside a repo is **project-scoped** (it can only act on that project's issues). On SSH/remote where no browser or loopback redirect is available, the flow auto-switches to the device flow — or force it with `insitue login --device`. As a CI / headless fallback, paste a Personal Access Token directly with `insitue login --token pat_live_…` (mint PATs at <https://app.insitue.com/app/settings/developer>); PATs are account-wide.
+2. **Link your project:** `insitue login` already best-effort auto-links the current repo to its InSitue project, so this is usually unnecessary. If you need to link manually, run `insitue link` (auto-detects the project from the git remote) or `insitue link <projectId>` in your project root. The tools read the linked project from `.insitue/project.json`.
 
 ### The loop
 
@@ -352,7 +361,7 @@ The plugin is a stdio MCP server that:
 
 | Tool | Purpose |
 |---|---|
-| `next_pick` | Long-poll for the next browser pick (default 25 s; max 30 min). |
+| `next_pick` | Long-poll for the next browser pick (default 8 s; max 30 min). |
 | `list_recent_picks` | Up to N buffered picks since the MCP server started. |
 | `start_session` | Returns the operating instructions + current state. Desktop entry point. |
 | `end_session` | Cleanly disconnect: close WS, suppress reconnect, kill spawned companion, drop session file. |
@@ -364,6 +373,9 @@ The plugin is a stdio MCP server that:
 | `claim_cloud_issue` | Claim an issue by `id`; returns note, source `file:line`, page URL, and top console errors. |
 | `resolve_cloud_issue` | Mark an issue resolved; attach `prUrl` and optional `branch`. |
 | `release_cloud_issue` | Return a claimed issue to the open queue. |
+| `authenticate` | Start browser sign-in (PKCE): chooses the device vs loopback flow automatically and returns the authorize URL + code to confirm. |
+| `complete_authentication` | Poll for approval (~5 min), then save credentials and best-effort auto-link the current repo to its project. |
+| `logout` | Revoke the token server-side and clear local credentials. |
 
 All file tools resolve paths against the project dir and refuse
 anything that resolves outside it (realpath-checked, so `..` games

package/commands/connect.md

@@ -64,18 +64,33 @@ your context and skip any id you've already processed.
 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.
-   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
-   (~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"`:
+   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.
+   >
+   > 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`.
+
+2. **Watch for a pick — ONE poll, then hand control back.** Call
+   `mcp__insitue__next_pick` (it long-polls ~8s).
+   - On `status: "timeout"` (no pick this window): **STOP. Do NOT
+     silently call `next_pick` again.** Parking yourself in back-to-back
+     polls FREEZES the session — a tool call can't be interrupted, so the
+     user types a message and you never see it (this is the #1 cause of
+     "InSitue is blocking me"). Instead, end your turn and hand control
+     back with one short line, e.g.:
+
+     > 👀 Watching. Pick something in the browser, or type anything — I'll
+     > 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).
+   - On `status: "ok"` (a pick arrived):
    - **Always echo the prompt back first.** Before any action,
      diff, or follow-up question, lead with:
 
@@ -105,20 +120,22 @@ your context and skip any id you've already processed.
      Don't auto-apply.
    - 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. **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. **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.
+   - Then call `next_pick` once more to catch a rapid follow-up pick.
+     When it times out (picks have stopped), fall back to the
+     hand-back rule above — yield to the user; do NOT loop forever.
+3. **On each user message: drain picks first, then answer, then resume.**
+   Whenever the user sends a message, before responding call `next_pick`
+   with a short `timeout_ms` (e.g. `1500`), repeatedly, until it returns
+   `status: "timeout"` — handle each pick it returns (de-dupe by `id`).
+   This catches anything the user picked while you were idle; picks are
+   buffered server-side, so nothing is lost. Then answer the user's
+   message fully and do whatever they ask. Then resume watching with a
+   single `next_pick` poll (step 2's one-poll-then-hand-back rule).
+
+   The user's message is ALWAYS the priority. Never tell them to cancel
+   or re-run `/insitue:connect` to talk to you, and never narrate the
+   watch ("still waiting…", "polling again…") — the browser already shows
+   `[insitue] 📥 pick received` the moment a pick lands.
 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/commands/login.md

@@ -10,9 +10,13 @@ Cloud issues will become available via the claude-plugin tools once signed in.
 
 ## Your behaviour
 
-1. Call `mcp__insitue__authenticate` (no arguments).
+1. Call `mcp__insitue__authenticate` (no arguments). It auto-detects the
+   environment: it opens a loopback browser flow locally, and automatically
+   switches to the device flow when an SSH session is detected or no loopback
+   port is available. Branch on the returned shape:
 
-2. The tool returns `{ status: "browser_opened", url, userCode, message }`.
+2. **Loopback flow** — the tool returns
+   `{ status: "browser_opened", url, userCode, message }`.
    Show the user:
 
    > I've opened your browser to sign in to InSitue. Please:
@@ -21,11 +25,20 @@ Cloud issues will become available via the claude-plugin tools once signed in.
    >
    > (If your browser didn't open, visit this URL manually: `<url>`)
 
-   Do NOT proceed to step 3 until the user says they've approved or you
-   detect they're ready. Wait for the user to confirm.
+   **Device flow** — the tool instead returns a device-flow shape with a
+   `verificationUrl` and `userCode` (no loopback redirect). This is what you'll
+   get over SSH or when no loopback port is free. Show the user:
 
-3. Call `mcp__insitue__complete_authentication` (no arguments).
-   This waits up to 5 minutes for the browser approval.
+   > To sign in to InSitue, open this URL in any browser:
+   > **`<verificationUrl>`**
+   >
+   > Then confirm the code matches: **`<userCode>`**
+
+   In both flows, do NOT proceed to step 3 until the user says they've approved
+   or you detect they're ready. Wait for the user to confirm.
+
+3. Call `mcp__insitue__complete_authentication` (no arguments). This polls
+   for the browser approval (up to ~5 minutes) for either flow.
 
 4. On `{ status: "ok" }`:
    - If `linked: true`: reply "Signed in as **@`<login>`** and linked to

package/dist/{chunk-BZDEEE6O.js → chunk-B2OV76P2.js}

@@ -19,8 +19,8 @@ var SUCCESS_HTML = `<!DOCTYPE html>
 <head><meta charset="utf-8"><title>InSitue \u2014 signed in</title>
 <style>body{font-family:system-ui,sans-serif;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0;background:#f9fafb;}
 .card{background:#fff;border-radius:12px;padding:40px 48px;text-align:center;box-shadow:0 1px 4px rgba(0,0,0,.12);}
-h1{font-size:1.4rem;margin:0 0 8px;}p{color:#6b7280;margin:0;}</style></head>
-<body><div class="card"><h1>You're signed in to InSitue</h1>
+h1{font-size:1.4rem;margin:0 0 8px;background:linear-gradient(180deg,#6b63ff,#5751e6);-webkit-background-clip:text;background-clip:text;color:transparent;}p{color:#6b7280;margin:0;}</style></head>
+<body><div class="card"><h1>You're signed in to InSitue!</h1>
 <p>You can close this tab and return to your terminal.</p></div></body></html>`;
 var ERROR_HTML = `<!DOCTYPE html>
 <html lang="en">

package/dist/cloud/login.js

@@ -3,7 +3,7 @@ import {
   genPkce,
   pickProjectIdForRepo,
   startLogin
-} from "../chunk-BZDEEE6O.js";
+} from "../chunk-B2OV76P2.js";
 export {
   detectGitRemote,
   genPkce,

package/dist/cloud-cli.js

@@ -16,7 +16,7 @@ import {
   detectGitRemote,
   pickProjectIdForRepo,
   startLogin
-} from "./chunk-BZDEEE6O.js";
+} from "./chunk-B2OV76P2.js";
 
 // src/cloud-cli.ts
 import { hostname } from "os";

package/dist/mcp-server.js

@@ -26,7 +26,7 @@ import {
   detectGitRemote,
   pickProjectIdForRepo,
   startLogin
-} from "./chunk-BZDEEE6O.js";
+} from "./chunk-B2OV76P2.js";
 
 // src/mcp-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/package.json

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