claude-ide-bridge 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Oolab Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,263 @@
+# Claude IDE Bridge
+
+[![npm version](https://img.shields.io/npm/v/claude-ide-bridge)](https://www.npmjs.com/package/claude-ide-bridge)
+[![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) full IDE integration — **115+ tools** for LSP, debugging, terminals, Git, GitHub, diagnostics, and more. Works with any VS Code-compatible editor (VS Code, Windsurf, Cursor) and pairs with a companion extension for real-time editor state.
+
+## How It Works
+
+```
+Your Phone / Laptop                    Your Computer
+┌──────────────┐                      ┌─────────────────────────────┐
+│  Claude Code  │───── SSH/local ─────│  Bridge Server              │
+│  (CLI)        │                     │    ↕ WebSocket              │
+└──────────────┘                      │  IDE Extension (VS Code)    │
+                                      │    ↕ Real-time state        │
+                                      │  Your Code & Editor         │
+                                      └─────────────────────────────┘
+```
+
+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.
+
+**Use it from your phone**: SSH into your dev machine, run Claude Code, and control your full IDE from the couch. Watch files change in real-time on your monitor.
+
+## Quick Start
+
+```bash
+npm install -g claude-ide-bridge
+
+# Start the bridge
+claude-ide-bridge --workspace /path/to/your-project
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/Oolab-labs/claude-ide-bridge.git
+cd claude-ide-bridge
+npm install && npm run build
+npm start -- --workspace /path/to/your-project
+```
+
+Install the VS Code extension for full capabilities:
+
+```bash
+cd vscode-extension
+npm install && npm run build && npm run package
+# Install the .vsix in your editor
+```
+
+Then start Claude Code and connect:
+
+```bash
+claude
+# The bridge MCP server will be available
+```
+
+## Full Orchestrator
+
+The `start-all` script launches everything in a tmux session (bridge + Claude Code + remote control):
+
+```bash
+npm run start-all -- --workspace /path/to/your-project
+```
+
+## Claude Code Plugin
+
+The bridge ships as a **Claude Code plugin** with 6 skills, 3 subagents, and 3 hooks:
+
+```bash
+# Load the plugin
+claude --plugin-dir ./claude-ide-bridge-plugin
+```
+
+### Skills
+
+| Skill | Description |
+|-------|-------------|
+| `/ide-debug` | Full debug cycle: run tests, set breakpoints, evaluate expressions, fix, verify |
+| `/ide-review` | Deep PR review using LSP code intelligence + GitHub tools |
+| `/ide-quality` | Multi-language lint sweep + auto-fix + format + optional commit |
+| `/ide-refactor` | Safe refactoring with snapshot checkpoints and auto-rollback |
+| `/ide-explore` | Codebase exploration using LSP (runs in isolated Explore agent) |
+| `/ide-monitor` | Continuous monitoring for diagnostics, tests, or terminal output |
+
+### Subagents
+
+| Agent | Description |
+|-------|-------------|
+| `ide-code-reviewer` | Evidence-based code review using LSP tools, with persistent memory |
+| `ide-debugger` | Autonomous debug cycles with breakpoints and expression evaluation |
+| `ide-test-runner` | Runs tests, categorizes failures, applies fixes |
+
+### Hooks
+
+| Event | What it does |
+|-------|-------------|
+| `PostToolUse` on Edit/Write | Reminds Claude to check diagnostics after file edits |
+| `SessionStart` | Reports bridge status, connection, and tool count |
+| `SubagentStart` | Verifies bridge is alive before IDE subagents run |
+
+## 115+ MCP Tools
+
+### File Operations (7)
+`openFile` · `openDiff` · `saveDocument` · `close_tab` · `closeAllDiffTabs` · `checkDocumentDirty` · `getOpenEditors`
+
+### LSP / Code Intelligence (12)
+`goToDefinition` · `findReferences` · `getHover` · `getCodeActions` · `applyCodeAction` · `renameSymbol` · `searchSymbols` · `getDocumentSymbols` · `getCallHierarchy` · `getTypeHierarchy` · `getImplementations` · `getInlayHints`
+
+### Debugging (5)
+`setDebugBreakpoints` · `startDebugging` · `evaluateInDebugger` · `getDebugState` · `stopDebugging`
+
+### Terminal (7)
+`createTerminal` · `runInTerminal` · `waitForTerminalOutput` · `getTerminalOutput` · `listTerminals` · `sendTerminalInput` · `closeTerminal`
+
+### Git (15)
+`gitStatus` · `gitDiff` · `gitLog` · `gitAdd` · `gitCommit` · `gitPush` · `gitPull` · `gitBranch` · `gitCheckout` · `gitStash` · `gitBlame` · `gitMerge` · `gitRebase` · `gitTag` · `gitRemote`
+
+### GitHub (11)
+`githubCreatePR` · `githubViewPR` · `githubGetPRDiff` · `githubPostPRReview` · `githubListPRs` · `githubMergePR` · `githubCreateIssue` · `githubListIssues` · `githubViewIssue` · `githubListReleases` · `githubCreateRelease`
+
+### Diagnostics & Testing (3)
+`getDiagnostics` · `runTests` · `diffDebug`
+
+### Code Quality (3)
+`fixAllLintErrors` · `formatDocument` · `organizeImports`
+
+### Snapshots & Plans (10)
+`createSnapshot` · `restoreSnapshot` · `diffSnapshot` · `listSnapshots` · `deleteSnapshot` · `createPlan` · `updatePlan` · `getPlan` · `listPlans` · `deletePlan`
+
+### Editor State (7)
+`getCurrentSelection` · `getLatestSelection` · `getOpenEditors` · `getActiveEditor` · `getVisibleRange` · `revealRange` · `showMessage`
+
+### And More
+Text editing · Workspace management · HTTP requests · File watchers · Notebooks · Decorations · VS Code commands
+
+| Category | Count | Extension Required |
+|----------|------:|:-:|
+| File Operations | 7 | No |
+| Git | 15 | No |
+| GitHub | 11 | No (requires `gh`) |
+| LSP / Code Intelligence | 12 | Yes (with fallbacks) |
+| Editor State | 7 | Yes |
+| Text Editing | 5 | Yes |
+| Terminal | 7 | Yes |
+| Diagnostics & Testing | 3 | Mixed |
+| Code Quality | 3 | Yes |
+| Debug | 5 | Yes |
+| Decorations | 2 | Yes |
+| Workspace Management | 4 | No |
+| Snapshots & Plans | 10 | No |
+| HTTP | 2 | No |
+| VS Code Integration | 8 | Yes |
+| Notebooks | 3 | Yes |
+| **Total** | **~115** | |
+
+## Headless / CI Usage
+
+Use with `claude -p` for automation:
+
+```bash
+# Fix all lint errors
+claude -p "Use getDiagnostics to find all errors, then fix them" \
+  --mcp-config ./mcp-bridge.json
+
+# Run tests and fix failures
+claude -p "Run tests with runTests, fix any failures, and commit" \
+  --mcp-config ./mcp-bridge.json
+
+# Generate architecture overview
+claude -p "Map the project using getFileTree, getDocumentSymbols, and getCallHierarchy" \
+  --mcp-config ./mcp-bridge.json --output-format json
+```
+
+## Supported Editors
+
+| Editor | Status |
+|--------|--------|
+| VS Code | Supported |
+| Windsurf | Supported |
+| Cursor | Supported |
+| Google Antigravity | Supported |
+
+Install the extension in any supported editor:
+
+```bash
+bash scripts/install-extension.sh --ide <name>
+```
+
+## CLI Options
+
+```
+--workspace <path>        Workspace folder (default: cwd)
+--ide-name <name>         IDE name shown to Claude (default: auto-detect)
+--editor <cmd>            Editor CLI command (default: auto-detect)
+--port <number>           Force specific port (default: random)
+--linter <name>           Enable specific linter (repeatable; default: auto-detect)
+--allow-command <cmd>     Add command to execution allowlist (repeatable)
+--timeout <ms>            Command timeout in ms (default: 30000, max: 120000)
+--max-result-size <KB>    Max output size in KB (default: 512, max: 4096)
+--verbose                 Enable debug logging
+--help                    Show this help
+```
+
+## Architecture
+
+```
+claude-ide-bridge/
+  src/
+    bridge.ts         Main orchestrator
+    server.ts         HTTP/WebSocket server
+    transport.ts      MCP transport layer
+    extensionClient.ts Extension WebSocket client
+    config.ts         CLI args & config
+    tools/            115+ MCP tool implementations
+  vscode-extension/
+    src/extension.ts  VS Code extension
+    src/connection.ts WebSocket connection management
+    src/handlers/     Request handlers (terminal, lsp, debug, ...)
+  claude-ide-bridge-plugin/
+    skills/           6 slash commands
+    agents/           3 specialized subagents
+    hooks/            3 lifecycle automations
+    .mcp.json         MCP server config
+```
+
+## Connection Hardening
+
+Production-grade reliability:
+- WebSocket heartbeat (20s) with automatic reconnect
+- Sleep/wake detection via heartbeat gap monitoring
+- Circuit breaker with exponential backoff for timeout cascades
+- Generation counter preventing stale handler responses
+- Extension-required tool filtering when extension disconnects
+- 601 tests across bridge and extension
+
+## Building
+
+```bash
+# Bridge
+npm run build        # TypeScript compilation
+npm run dev          # Development with tsx
+npm test             # Run 359 bridge tests
+
+# Extension
+cd vscode-extension
+npm run build        # esbuild bundle
+npm run package      # Create .vsix
+npm test             # Run 242 extension tests
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and how to add new tools.
+
+## Support
+
+If Claude IDE Bridge saves you time, consider [sponsoring the project](https://github.com/sponsors/Oolab-labs).
+
+## License
+
+MIT

package/dist/activityLog.d.ts

@@ -0,0 +1,26 @@
+export interface ActivityEntry {
+    id: number;
+    timestamp: string;
+    tool: string;
+    durationMs: number;
+    status: "success" | "error";
+    errorMessage?: string;
+}
+export declare class ActivityLog {
+    private entries;
+    private nextId;
+    private maxEntries;
+    constructor(maxEntries?: number);
+    record(tool: string, durationMs: number, status: "success" | "error", errorMessage?: string): void;
+    query(opts?: {
+        tool?: string;
+        status?: string;
+        last?: number;
+    }): ActivityEntry[];
+    toPrometheus(): string;
+    stats(): Record<string, {
+        count: number;
+        avgDurationMs: number;
+        errors: number;
+    }>;
+}

package/dist/activityLog.js

@@ -0,0 +1,76 @@
+function escapeLabelValue(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+export class ActivityLog {
+    entries = [];
+    nextId = 1;
+    maxEntries;
+    constructor(maxEntries = 500) {
+        this.maxEntries = maxEntries;
+    }
+    record(tool, durationMs, status, errorMessage) {
+        this.entries.push({
+            id: this.nextId++,
+            timestamp: new Date().toISOString(),
+            tool,
+            durationMs,
+            status,
+            errorMessage,
+        });
+        if (this.entries.length > this.maxEntries * 1.2) {
+            // Batch eviction: drop the oldest 20% instead of shift() on every insert
+            this.entries = this.entries.slice(-this.maxEntries);
+        }
+    }
+    query(opts) {
+        let result = this.entries;
+        if (opts?.tool)
+            result = result.filter((e) => e.tool === opts.tool);
+        if (opts?.status)
+            result = result.filter((e) => e.status === opts.status);
+        const last = Math.min(opts?.last ?? 50, 200);
+        return result.slice(-last);
+    }
+    toPrometheus() {
+        const s = this.stats();
+        const lines = [];
+        lines.push("# HELP bridge_tool_calls_total Total tool calls by tool name and status");
+        lines.push("# TYPE bridge_tool_calls_total counter");
+        for (const [tool, data] of Object.entries(s)) {
+            const t = escapeLabelValue(tool);
+            lines.push(`bridge_tool_calls_total{tool="${t}",status="success"} ${data.count - data.errors}`);
+            lines.push(`bridge_tool_calls_total{tool="${t}",status="error"} ${data.errors}`);
+        }
+        lines.push("# HELP bridge_tool_duration_ms_avg Average tool duration in milliseconds");
+        lines.push("# TYPE bridge_tool_duration_ms_avg gauge");
+        for (const [tool, data] of Object.entries(s)) {
+            const t = escapeLabelValue(tool);
+            lines.push(`bridge_tool_duration_ms_avg{tool="${t}"} ${data.avgDurationMs}`);
+        }
+        lines.push("# HELP bridge_uptime_seconds Process uptime in seconds");
+        lines.push("# TYPE bridge_uptime_seconds gauge");
+        lines.push(`bridge_uptime_seconds ${Math.floor(process.uptime())}`);
+        return `${lines.join("\n")}\n`;
+    }
+    stats() {
+        const map = new Map();
+        for (const entry of this.entries) {
+            const s = map.get(entry.tool) ?? { count: 0, totalMs: 0, errors: 0 };
+            s.count++;
+            s.totalMs += entry.durationMs;
+            if (entry.status === "error")
+                s.errors++;
+            map.set(entry.tool, s);
+        }
+        const result = {};
+        for (const [tool, s] of map) {
+            result[tool] = {
+                count: s.count,
+                avgDurationMs: Math.round(s.totalMs / s.count),
+                errors: s.errors,
+            };
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=activityLog.js.map

package/dist/activityLog.js.map

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

package/dist/bridge.d.ts

@@ -0,0 +1,19 @@
+import type { Config } from "./config.js";
+export declare class Bridge {
+    private config;
+    private logger;
+    private lockFile;
+    private server;
+    private extensionClient;
+    private activityLog;
+    private authToken;
+    private sessions;
+    private fileLock;
+    private probes;
+    private stopped;
+    private listChangedTimer;
+    constructor(config: Config);
+    private cleanupSession;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}