# Claude IDE Bridge — Cursor Rules ## Build - Run `npm run build` for bridge, `cd vscode-extension && npm run build && npm run package` for extension. - Run `npx biome check .` before every commit. - Run `npm test` before every commit. - Always rebuild bridge + extension + VSIX before testing changes. ## Tool Pattern - Create tools using `createXxxTool(deps)` returning `{ schema, handler }`. - Register every tool in `src/tools/index.ts`. - Set `extensionRequired: true` if the tool needs the VS Code extension. - Tool names must match `/^[a-zA-Z0-9_]+$/`. - Use `readOnlyHint: true` in annotations for tools that do not modify state. - Never throw from a tool handler — catch and return `{ content: [...], isError: true }`. ## Extension Handlers - Create handlers as standalone async functions. - Register in `vscode-extension/src/handlers/index.ts`. - All `ws.send()` calls must use `safeSend()` or readyState check + try-catch. ## Error Handling - Tool execution errors: return `isError: true` in content blocks. See docs/adr/0004-tool-errors-as-content.md. - Protocol errors: use `ErrorCodes` (JSON-RPC -32xxx). Never mix the two. - Never use JSON-RPC error codes in tool handlers. ## Input Validation - All tool arguments are validated by AJV schemas at the transport layer. - Use `resolveFilePath()` for any user-supplied path — blocks null bytes, symlinks, and workspace escapes. - Use `isValidRef()` for git ref arguments — blocks leading-dash refs. - Clipboard operations enforce 1MB cap via `Buffer.byteLength`. - `searchAndReplace` rejects null bytes and `-`-prefixed glob patterns. ## Security - `runCommand` only executes allowlisted commands. Interpreter commands (node, python, bash) are permanently blocked. - `sendHttpRequest` blocks private/loopback IPs (SSRF). DNS pre-resolves hostnames. Host header overridden after user headers. - Never include auth tokens, IPs, or domain names in source code or documentation. - Lock files use `O_EXCL` creation (symlink attack prevention) and `chmod 0o600`. ## Testing - New bridge tools: add tests in `src/tools/__tests__/`. - New extension handlers: add tests in `vscode-extension/src/__tests__/handlers/`. - Use vitest for both. Coverage gates: 75% lines, 70% branches, 75% functions. - Bug fix protocol: write a failing test first, then fix. ## Version Numbers - `BRIDGE_PROTOCOL_VERSION` in `src/version.ts`: only bump when wire format changes. See docs/adr/0001-dual-version-numbers.md. - `PACKAGE_VERSION`: auto-read from package.json. Bump on every npm release. - Bumping package.json does NOT bump the protocol version. ## Lock Files - Lock files live at `~/.claude/ide/.lock` with `isBridge: true` to distinguish from IDE locks. See docs/adr/0003-isbridge-lock-file-flag.md. - Stale lock cleanup: check PID liveness + 24h age guard for PID reuse. - Directory mode `0o700`, file mode `0o600`. ## Plugin System - Scaffold: `claude-ide-bridge gen-plugin-stub --name --prefix `. - All plugin tool names must start with the manifest `toolNamePrefix`. - Entrypoint exports `register(ctx)`. ctx provides `workspace`, `workspaceFolders`, `config`, `logger`. - Manifest requires `schemaVersion: 1`. ## Reconnection - Every WebSocket callback must check `gen !== this.generation` before acting. See docs/adr/0002-generation-guards-on-reconnect.md. - HTTP sessions evict oldest idle (>60s) on capacity. 503 only when all sessions genuinely active. See docs/adr/0005-http-session-eviction.md. - Grace period (default 30s) preserves session state across brief disconnects. ## Rate Limiting - 200 requests/minute per session (ring buffer). - 500 notifications/minute per connection. - Tool calls: token bucket, default 60/min, configurable via `--tool-rate-limit`. - Failed AJV validation does not consume rate limit tokens. ## Documentation - `CLAUDE.md`: behavioral rules for AI assistants. Keep concise. No secrets. - `documents/`: deep reference docs. Do not duplicate content in CLAUDE.md. - `docs/adr/`: architecture decisions. Follow standard ADR template (Status, Context, Decision, Consequences).