claude-ide-bridge 2.6.0 → 2.6.2

package/README.md

@@ -4,33 +4,57 @@
 [![CI](https://github.com/Oolab-labs/claude-ide-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/Oolab-labs/claude-ide-bridge/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A standalone MCP bridge that gives [Claude Code](https://claude.ai/code) real IDE integration — not just file access, but **live editor state**: diagnostics as you type, go-to-definition, find-all-references, hover types, rename-symbol, set breakpoints, evaluate in the debugger, and capture what's on screen. Works with any VS Code-compatible editor (VS Code, Windsurf, Cursor) via a companion extension.
+**Claude Code, but with your IDE's eyes.**
 
-It also exposes Git, GitHub, terminals, and code analysis tools — but the core value is the LSP and debugger integration that Claude has no other way to access.
+A WebSocket bridge that connects Claude Code to VS Code (and Windsurf, Cursor) so Claude can see what your IDE sees: live diagnostics, go-to-definition, find references, hover types, open files, breakpoints, debugger state. Not file access — actual IDE context, the same signals a developer reads while working.
 
-## How It Works
+Install the companion extension, start the bridge, open Claude. That's it. Claude can now navigate your codebase the way you do, run tests, check diagnostics, commit, and create PRs — without you copy-pasting anything.
 
 ```
-Your Phone / Laptop                    Your Computer
-┌──────────────┐                      ┌─────────────────────────────┐
-│  Claude Code  │───── SSH/local ─────│  Bridge Server              │
-│  (CLI)        │◄── remote control ──│    ↕ WebSocket              │
-└──────────────┘                      │  IDE Extension (VS Code)    │
-                                      │    ↕ Real-time state        │
-       ┌──────────────────────────────│  Your Code & Editor         │
-       │   runClaudeTask              └─────────────────────────────┘
-       ▼
-┌──────────────┐
-│  claude -p   │  Autonomous subprocess — full tools, no approval loop
-│  subprocess  │  Output streams back to VS Code output channel
-└──────────────┘
+Claude Code ──── bridge ──── VS Code extension ──── your editor state
 ```
 
-Claude Code connects to the bridge, which connects to your IDE extension. Claude can then open files, run tests, set breakpoints, check diagnostics, commit to Git, create PRs — everything a developer at the keyboard can do.
+**Works from your phone.** SSH into your dev machine, send a message, watch Claude fix bugs and run tests on your home machine while you're away.
 
-**Use it from your phone**: SSH into your dev machine, send a message via remote control, and delegate autonomous work to a `claude -p` subprocess running on your home machine. Watch it fix bugs, run tests, and commit — then go back to sleep.
+## Pick your path
 
-**Autonomous task mode**: With `--claude-driver subprocess`, the bridge can spawn Claude subprocesses on demand via the `runClaudeTask` MCP tool. Tasks run in parallel (up to 10 concurrent), stream output to VS Code in real time, and can be triggered automatically by diagnostics or file saves via an automation policy.
+| I want to… | Go to |
+|---|---|
+| Get started (5 min setup) | [Quick Start](#quick-start) |
+| Understand what tools are available | [Platform Docs](documents/platform-docs.md) |
+| Run two IDEs in parallel | [Multi-IDE Orchestrator](#multi-ide-orchestrator) |
+| Access from remote / phone | [Remote Access](docs/remote-access.md) |
+| Deploy to a VPS | [Deploy](deploy/README.md) |
+| Write a plugin | [Plugin Authoring](documents/plugin-authoring.md) |
+| Use with Claude Desktop / Dispatch | [Session Continuity](#session-continuity) |
+| Use with claude.ai web | [Custom Connector](#use-with-claudeai-web) |
+
+## Quick Start
+
+**Prerequisites:** [Claude Code CLI](https://claude.ai/code), Node.js ≥ 20
+
+```bash
+npm install -g claude-ide-bridge
+cd /your/project
+claude-ide-bridge init
+```
+
+`init` installs the VS Code extension, writes a `## Claude IDE Bridge` section to your `CLAUDE.md`, and registers the bridge as a global MCP server in `~/.claude.json` — so bridge tools are available in **every** `claude` session (any directory, any IDE). That's the entire setup.
+
+**Then start the bridge and open Claude:**
+
+```bash
+claude-ide-bridge --watch   # terminal 1 — keeps running, auto-restarts on crash
+claude --ide                # terminal 2 — Claude Code with IDE tools active
+```
+
+Type `/mcp` in Claude to confirm the server is connected, then `/ide` to see open files, diagnostics, and editor state.
+
+> **One bridge per workspace.** Each project needs its own bridge instance on its own port. If you work across multiple repos, start a separate `claude-ide-bridge --watch` in each directory.
+
+> **Why `~/.claude.json` and not `.mcp.json`?** When VS Code, Windsurf, or Cursor launches Claude Code, it injects `--mcp-config` which overrides any project `.mcp.json`. Only `~/.claude.json` is loaded in every session regardless of how Claude Code is started. `init` writes there by design — you don't need to touch `.mcp.json`.
+
+**Tools not showing up?** See the [troubleshooting guide](docs/troubleshooting.md).
 
 ## Multi-IDE Orchestrator
 
@@ -66,35 +90,13 @@ Use `switchWorkspace ws1` / `switchWorkspace ws2` in Claude to pin to a specific
 
 See [docs/multi-ide-review.md](docs/multi-ide-review.md) for the staged review workflow.
 
-## Quick Start
-
-**Prerequisites:** [Claude Code CLI](https://claude.ai/code), Node.js ≥ 20
-
-```bash
-npm install -g claude-ide-bridge
-cd /your/project
-claude-ide-bridge init
-```
-
-`init` installs the VS Code extension, writes a `## Claude IDE Bridge` section to your `CLAUDE.md`, and prints the two remaining steps (env var + how to start). That's the entire setup.
-
-**Then start the bridge and open Claude:**
-
-```bash
-claude-ide-bridge --watch   # terminal 1 — keeps running, auto-restarts on crash
-claude --ide                # terminal 2 — Claude Code with IDE tools active
-```
-
-Type `/ide` in Claude to confirm — you'll see open files, diagnostics, and editor state.
-
-> **One bridge per workspace.** Each project needs its own bridge instance on its own port. If you work across multiple repos, start a separate `claude-ide-bridge --watch` in each directory.
-
 ## Documentation
 
 > **These guides are essential for setup and deployment** — not optional reading. Each covers a specific scenario you'll encounter when running the bridge beyond localhost.
 
 | Guide | What it covers |
 |-------|----------------|
+| **[Troubleshooting](docs/troubleshooting.md)** | Tools not showing up, wrong config file, WSL/Windows PATH, port conflicts |
 | **[Remote Access](docs/remote-access.md)** | Production reverse proxy setup (Caddy/nginx), TLS, Streamable HTTP transport |
 | **[SSH Resilience](docs/ssh-resilience.md)** | Surviving SSH drops, tmux strategies, phone-to-VPS workflows |
 | **[IP Allowlist](docs/ip-allowlist.md)** | Firewall rules, network access control for remote bridge instances |
@@ -102,6 +104,7 @@ Type `/ide` in Claude to confirm — you'll see open files, diagnostics, and edi
 | **[Privacy Policy](docs/privacy-policy.md)** | What data the bridge handles, stores, and never transmits |
 | **[Demo Setup](docs/demo-setup.md)** | Standing up a persistent demo instance for review/testing |
 | **[Architecture Decisions](docs/adr/)** | ADRs for version numbers, reconnect guards, lock files, error model, session eviction |
+| **[Release Checklist](docs/release-checklist.md)** | Pre-release gate: hardcoded count audit, doc completeness, publish steps |
 
 **Reference docs** (in [`documents/`](documents/)):
 
@@ -160,7 +163,7 @@ Requires `tmux` and the `claude` CLI to be on `PATH`.
 
 ## Claude Code Plugin
 
-The bridge ships as a **Claude Code plugin** with 9 skills, 3 subagents, and 7 hook events — available on the [Claude Code plugin directory](https://claude.com/plugins):
+The bridge ships as a **Claude Code plugin** with 9 skills, 3 subagents, and 16 hook events — available on the [Claude Code plugin directory](https://claude.com/plugins):
 
 ```bash
 # Load the plugin
@@ -195,20 +198,29 @@ claude --plugin-dir ./claude-ide-bridge-plugin
 
 | Event | What it does |
 |-------|-------------|
-| `PreToolUse` on Edit/Write | Resolves relative path args to absolute before bridge tools execute |
+| `PreToolUse` | Resolves relative path args to absolute before bridge tools execute |
 | `PostToolUse` on Edit/Write | Reminds Claude to check diagnostics after file edits |
 | `SessionStart` | Reports bridge status, connection, and tool count |
 | `InstructionsLoaded` | Injects live bridge status each time CLAUDE.md loads |
 | `Elicitation` | Pre-fills file/path/uri fields using the active editor |
+| `ElicitationResult` | Logs user responses (or cancellations) to MCP elicitation dialogs |
+| `PostCompact` | Re-injects bridge status after Claude compacts context |
 | `WorktreeCreate` | Reports bridge ↔ worktree relationship; warns about LSP limitations |
+| `WorktreeRemove` | Warns that IDE state may be stale after worktree removal |
 | `SubagentStart` | Verifies bridge is alive before IDE subagents run |
+| `SubagentStop` | Surfaces subagent final response summary for parent agent awareness |
+| `TeammateIdle` | Reports bridge health when a team agent finishes and awaits coordination |
+| `TaskCompleted` | Logs task completion summary and confirms bridge availability |
+| `ConfigChange` | Warns if changed config files require a bridge restart |
+| `Stop` | Logs session end and surfaces final response for automated workflows |
+| `StopFailure` | Logs API errors that ended the turn; checks bridge health |
 
 ## MCP Tools
 
 The bridge exposes tools in two modes:
 
 - **Slim mode (default)** — 27 IDE-exclusive tools. Only tools that require a live VS Code extension and have no native Claude equivalent. This is what you get with `claude-ide-bridge --watch`.
-- **Full mode (`--full`)** — all ~95 tools, adding git, terminal, file ops, HTTP, and GitHub. Use this for large projects or workflows that rely on those integrations.
+- **Full mode (`--full`)** — all ~96 tools, adding git, terminal, file ops, HTTP, and GitHub. Use this for large projects or workflows that rely on those integrations.
 
 ### Slim mode — 27 IDE tools (default)
 

package/dist/analyticsAggregator.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Aggregates ActivityLog data into an anonymized session summary for opt-in
+ * usage analytics. No file paths, arguments, error messages, or personal data.
+ *
+ * Plugin tool names are hashed (prefix only) to avoid leaking org-specific names.
+ * Built-in tool names are sent verbatim.
+ */
+export interface ToolStat {
+    tool: string;
+    calls: number;
+    errors: number;
+    p50Ms: number;
+    p95Ms: number;
+}
+export interface AnalyticsSummary {
+    bridgeVersion: string;
+    sessionDurationMs: number;
+    toolStats: ToolStat[];
+}
+/**
+ * Build an anonymized summary from raw tool call entries.
+ * Accepts the same shape as ActivityLog.stats() plus raw duration arrays.
+ */
+export declare function buildSummary(entries: Array<{
+    tool: string;
+    durationMs: number;
+    status: "success" | "error";
+}>, sessionDurationMs: number, bridgeVersion: string): AnalyticsSummary;

package/dist/analyticsAggregator.js

@@ -0,0 +1,133 @@
+/**
+ * Aggregates ActivityLog data into an anonymized session summary for opt-in
+ * usage analytics. No file paths, arguments, error messages, or personal data.
+ *
+ * Plugin tool names are hashed (prefix only) to avoid leaking org-specific names.
+ * Built-in tool names are sent verbatim.
+ */
+import crypto from "node:crypto";
+/** Known built-in tool names — sent verbatim. Anything else is treated as a plugin tool. */
+const BUILTIN_TOOL_NAMES = new Set([
+    "getOpenEditors",
+    "getCurrentSelection",
+    "getLatestSelection",
+    "getDiagnostics",
+    "watchDiagnostics",
+    "getDocumentSymbols",
+    "getHover",
+    "goToDefinition",
+    "findReferences",
+    "getCallHierarchy",
+    "searchWorkspaceSymbols",
+    "getCodeActions",
+    "applyCodeAction",
+    "renameSymbol",
+    "openFile",
+    "closeTab",
+    "checkDocumentDirty",
+    "saveDocument",
+    "captureScreenshot",
+    "getBridgeStatus",
+    "getToolCapabilities",
+    "executeVSCodeCommand",
+    "getDebugState",
+    "setDebugBreakpoints",
+    "startDebugging",
+    "stopDebugging",
+    "evaluateInDebugger",
+    "readFile",
+    "writeFile",
+    "createFile",
+    "deleteFile",
+    "moveFile",
+    "listDirectory",
+    "searchFiles",
+    "searchAndReplace",
+    "runCommand",
+    "getGitStatus",
+    "getGitDiff",
+    "gitCommit",
+    "gitCheckout",
+    "gitPush",
+    "gitPull",
+    "gitLog",
+    "gitWrite",
+    "sendHttpRequest",
+    "clipboardRead",
+    "clipboardWrite",
+    "getClipboard",
+    "setClipboard",
+    "openDiff",
+    "runClaudeTask",
+    "getClaudeTaskStatus",
+    "cancelClaudeTask",
+    "listClaudeTasks",
+    "resumeClaudeTask",
+    "getAIComments",
+    "createGithubIssueFromAIComment",
+    "switchWorkspace",
+    "getOrchestratorStatus",
+    "handoffNote",
+    "workspaceSettings",
+    "getHandoffNote",
+    "writeHandoffNote",
+    "logging",
+]);
+/** Returns the safe tool name to include in analytics. */
+function safeToolName(tool) {
+    if (BUILTIN_TOOL_NAMES.has(tool))
+        return tool;
+    // Plugin tool: extract prefix (everything before first underscore) and hash it
+    const prefix = tool.includes("_") ? (tool.split("_")[0] ?? tool) : tool;
+    const hash = crypto
+        .createHash("sha256")
+        .update(prefix)
+        .digest("hex")
+        .slice(0, 8);
+    return `plugin:${hash}`;
+}
+/** Compute p50 and p95 from a sorted array of durations. */
+function percentiles(sorted) {
+    if (sorted.length === 0)
+        return { p50: 0, p95: 0 };
+    const p50 = sorted[Math.floor(sorted.length * 0.5)] ?? 0;
+    const p95 = sorted[Math.floor(sorted.length * 0.95)] ?? 0;
+    return { p50, p95 };
+}
+/**
+ * Build an anonymized summary from raw tool call entries.
+ * Accepts the same shape as ActivityLog.stats() plus raw duration arrays.
+ */
+export function buildSummary(entries, sessionDurationMs, bridgeVersion) {
+    // Group by safe tool name
+    const map = new Map();
+    for (const entry of entries) {
+        const name = safeToolName(entry.tool);
+        const s = map.get(name) ?? { calls: 0, errors: 0, durations: [] };
+        s.calls++;
+        if (entry.status === "error")
+            s.errors++;
+        s.durations.push(entry.durationMs);
+        map.set(name, s);
+    }
+    const toolStats = [];
+    for (const [tool, s] of map) {
+        const sorted = [...s.durations].sort((a, b) => a - b);
+        const { p50, p95 } = percentiles(sorted);
+        toolStats.push({
+            tool,
+            calls: s.calls,
+            errors: s.errors,
+            p50Ms: Math.round(p50),
+            p95Ms: Math.round(p95),
+        });
+    }
+    // Sort by call count descending for readability
+    toolStats.sort((a, b) => b.calls - a.calls);
+    return {
+        bridgeVersion,
+        sessionDurationMs,
+        toolStats,
+    };
+}
+//# sourceMappingURL=analyticsAggregator.js.map

package/dist/analyticsAggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyticsAggregator.js","sourceRoot":"","sources":["../src/analyticsAggregator.ts"],"names":[],"mappings":"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"}

package/dist/analyticsPrefs.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reads and writes the opt-in analytics preference.
+ * Stored in ~/.claude/ide/analytics.json (respects CLAUDE_CONFIG_DIR).
+ * File created with 0o600 permissions (owner read/write only).
+ */
+/** Returns the current opt-in state, or null if no preference has been set. */
+export declare function getAnalyticsPref(): boolean | null;
+/** Persists the opt-in preference. Creates file with 0o600 permissions. */
+export declare function setAnalyticsPref(enabled: boolean): void;

package/dist/analyticsPrefs.js

@@ -0,0 +1,50 @@
+/**
+ * Reads and writes the opt-in analytics preference.
+ * Stored in ~/.claude/ide/analytics.json (respects CLAUDE_CONFIG_DIR).
+ * File created with 0o600 permissions (owner read/write only).
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function prefsPath() {
+    const claudeDir = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
+    return path.join(claudeDir, "ide", "analytics.json");
+}
+/** Returns the current opt-in state, or null if no preference has been set. */
+export function getAnalyticsPref() {
+    const p = prefsPath();
+    try {
+        const raw = fs.readFileSync(p, "utf-8");
+        const obj = JSON.parse(raw);
+        if (typeof obj === "object" &&
+            obj !== null &&
+            "enabled" in obj &&
+            typeof obj.enabled === "boolean") {
+            return obj.enabled;
+        }
+        return null;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return null;
+        return null;
+    }
+}
+/** Persists the opt-in preference. Creates file with 0o600 permissions. */
+export function setAnalyticsPref(enabled) {
+    const p = prefsPath();
+    const dir = path.dirname(p);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const content = {
+        enabled,
+        decidedAt: new Date().toISOString(),
+    };
+    // Write to temp file then rename for atomicity
+    const tmp = `${p}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(content, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    fs.renameSync(tmp, p);
+}
+//# sourceMappingURL=analyticsPrefs.js.map

package/dist/analyticsPrefs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyticsPrefs.js","sourceRoot":"","sources":["../src/analyticsPrefs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAO7B,SAAS,SAAS;IAChB,MAAM,SAAS,GACb,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IACtE,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,gBAAgB,CAAC,CAAC;AACvD,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB;IAC9B,MAAM,CAAC,GAAG,SAAS,EAAE,CAAC;IACtB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;QACvC,IACE,OAAO,GAAG,KAAK,QAAQ;YACvB,GAAG,KAAK,IAAI;YACZ,SAAS,IAAI,GAAG;YAChB,OAAQ,GAAiB,CAAC,OAAO,KAAK,SAAS,EAC/C,CAAC;YACD,OAAQ,GAAiB,CAAC,OAAO,CAAC;QACpC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC/C,MAAM,CAAC,GAAG,SAAS,EAAE,CAAC;IACtB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5B,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpD,MAAM,OAAO,GAAc;QACzB,OAAO;QACP,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IACF,+CAA+C;IAC/C,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC;IACvB,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;QAC7D,IAAI,EAAE,KAAK;KACZ,CAAC,CAAC;IACH,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;AACxB,CAAC"}

package/dist/analyticsSend.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Sends an anonymized analytics summary to the usage endpoint.
+ * - Fire-and-forget is NOT used: callers must await this with a timeout race.
+ * - All errors are caught and swallowed — telemetry must never affect bridge operation.
+ * - Endpoint is hardcoded (not runtime-configurable) to prevent redirect attacks.
+ */
+import type { AnalyticsSummary } from "./analyticsAggregator.js";
+/**
+ * Sends the summary to the analytics endpoint.
+ * Resolves (never rejects) — all errors are swallowed silently.
+ */
+export declare function sendAnalytics(summary: AnalyticsSummary): Promise<void>;

package/dist/analyticsSend.js

@@ -0,0 +1,34 @@
+/**
+ * Sends an anonymized analytics summary to the usage endpoint.
+ * - Fire-and-forget is NOT used: callers must await this with a timeout race.
+ * - All errors are caught and swallowed — telemetry must never affect bridge operation.
+ * - Endpoint is hardcoded (not runtime-configurable) to prevent redirect attacks.
+ */
+/** Hardcoded endpoint — not configurable at runtime. */
+const ANALYTICS_ENDPOINT = "https://analytics.claude-ide-bridge.dev/v1/usage";
+const SEND_TIMEOUT_MS = 3000;
+/**
+ * Sends the summary to the analytics endpoint.
+ * Resolves (never rejects) — all errors are swallowed silently.
+ */
+export async function sendAnalytics(summary) {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), SEND_TIMEOUT_MS);
+        try {
+            await fetch(ANALYTICS_ENDPOINT, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(summary),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch {
+        // Silently swallow all errors — telemetry must never surface to the user
+    }
+}
+//# sourceMappingURL=analyticsSend.js.map

package/dist/analyticsSend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyticsSend.js","sourceRoot":"","sources":["../src/analyticsSend.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,wDAAwD;AACxD,MAAM,kBAAkB,GAAG,kDAAkD,CAAC;AAE9E,MAAM,eAAe,GAAG,IAAI,CAAC;AAE7B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAyB;IAC3D,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,eAAe,CAAC,CAAC;QACpE,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,kBAAkB,EAAE;gBAC9B,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;gBAC7B,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;IAC3E,CAAC;AACH,CAAC"}

package/dist/bridge.d.ts

@@ -39,6 +39,7 @@ export declare class Bridge {
     /** Debounced tools/list_changed notification — max one per 2 seconds. */
     private sendListChanged;
     private _buildCheckpoint;
+    private buildInstructions;
     private cleanupSession;
     /** Returns the port the bridge is listening on (0 before start()). */
     getPort(): number;

package/dist/bridge.js

@@ -3,6 +3,9 @@ import os from "node:os";
 import path from "node:path";
 import { WebSocket } from "ws";
 import { ActivityLog } from "./activityLog.js";
+import { buildSummary } from "./analyticsAggregator.js";
+import { getAnalyticsPref } from "./analyticsPrefs.js";
+import { sendAnalytics } from "./analyticsSend.js";
 import { AutomationHooks, loadPolicy } from "./automation.js";
 import { createDriver } from "./claudeDriver.js";
 import { ClaudeOrchestrator } from "./claudeOrchestrator.js";
@@ -23,6 +26,7 @@ import { registerAllTools } from "./tools/index.js";
 import { cleanupTempDirs } from "./tools/openDiff.js";
 import { resolveFilePath } from "./tools/utils.js";
 import { McpTransport } from "./transport.js";
+import { PACKAGE_VERSION } from "./version.js";
 const SHUTDOWN_TIMEOUT_MS = 5000;
 const MAX_SESSIONS = 5;
 let globalHandlersRegistered = false;
@@ -124,6 +128,7 @@ export class Bridge {
             transport.setActivityLog(this.activityLog);
             transport.setToolRateLimit(this.config.toolRateLimit);
             transport.setExtensionConnectedFn(() => this.extensionClient.isConnected());
+            transport.setInstructions(this.buildInstructions());
             transport.onInitialized = () => {
                 if (this.pendingListChanged && ws.readyState === WebSocket.OPEN) {
                     McpTransport.sendNotification(ws, "notifications/tools/list_changed", undefined, this.logger);
@@ -350,6 +355,16 @@ export class Bridge {
             gracePeriodMs: this.config.gracePeriodMs,
         };
     }
+    buildInstructions() {
+        const lines = [`claude-ide-bridge v${PACKAGE_VERSION}`];
+        lines.push("");
+        lines.push("CONTEXT PLATFORM:");
+        lines.push("  Use ctx tools for issue/PR/error context — not gh or githubViewPR.");
+        lines.push("  ctxGetTaskContext(ref) — unified context for any issue, PR, commit, or error");
+        lines.push("  ctxQueryTraces(query) — search past decisions");
+        lines.push("  ctxSaveTrace(ref, problem, solution) — record fix after resolving a task");
+        return lines.join("\n");
+    }
     cleanupSession(id) {
         const session = this.sessions.get(id);
         if (!session)
@@ -523,7 +538,7 @@ export class Bridge {
         // 3b. Set up Streamable HTTP transport handler (POST/GET/DELETE /mcp)
         this.httpMcpHandler = new StreamableHttpHandler(this.config, probes, this.extensionClient, this.activityLog, this.fileLock, this.sessions, this.orchestrator, this.logger, () => this.pluginWatcher?.getTools() ?? this.pluginTools, () => this.pluginWatcher, this.oauthServer
             ? (token) => this.oauthServer?.resolveBearerScope(token) ?? null
-            : null);
+            : null, this.buildInstructions());
         this.server.httpMcpHandler = (req, res) => this.httpMcpHandler?.handle(req, res) ?? Promise.resolve();
         // 3. Check for stale lock files
         this.lockFile.cleanStale();
@@ -684,6 +699,23 @@ export class Bridge {
             ? `, ${totalErrors} error${totalErrors === 1 ? "" : "s"}`
             : "";
         this.logger.info(`Shutdown complete — ${totalSessions} session${totalSessions === 1 ? "" : "s"}, ${totalCalls} tool call${totalCalls === 1 ? "" : "s"}${shutdownErrorPart}`);
+        // Send analytics if opted in — awaited with 2s timeout so it completes before process.exit()
+        const analyticsOn = this.config.analyticsEnabled !== null
+            ? this.config.analyticsEnabled
+            : getAnalyticsPref();
+        if (analyticsOn === true && totalSessions > 0) {
+            try {
+                const entries = this.activityLog.query({ last: 500 });
+                const summary = buildSummary(entries, maxDurationMs, PACKAGE_VERSION);
+                await Promise.race([
+                    sendAnalytics(summary),
+                    new Promise((resolve) => setTimeout(resolve, 2000)),
+                ]);
+            }
+            catch {
+                // Swallow all errors — analytics must never affect shutdown
+            }
+        }
         // Send aggregate session-end notification to the extension before disconnecting
         if (totalSessions > 0) {
             this.extensionClient.notifyClaudeConnectionState(false, {