Claude IDE Bridge & Patchwork OS

One npm package. Two products. Pick the layer you need.

Same codebase. Bridge is the foundation; Patchwork OS is the optional layer on top. No vendor lock-in. Runs on your machine.

🔌 Claude IDE Bridge — Quick Start

# 1. Install the npm package
npm install -g patchwork-os

# 2. Install the VS Code / Cursor / Windsurf extension
#    Search "Claude IDE Bridge" on OpenVSX, or:
claude-ide-bridge install-extension

# 3. Start the bridge for your workspace
claude-ide-bridge --workspace .

# 4. Connect Claude Code (in another terminal)
CLAUDE_CODE_IDE_SKIP_VALID_CHECK=true claude --ide

Type /ide in Claude Code to confirm the connection. That's it — Claude now sees your diagnostics, open files, and editor state, and can call 170+ tools to act on them.

What the bridge gives Claude:

• Diagnostics, LSP navigation (goto / references / call hierarchy), refactoring with risk analysis
• Terminal — run commands, read output, wait for async work
• Git — status, diff, commit, push, blame, checkout, branch list
• GitHub — open PRs, list issues, post reviews, fetch run logs
• Debugger — set breakpoints, evaluate expressions, inspect runtime state
• Files — read, edit by line range, search and replace, capture screenshots
• Code quality — auditDependencies, detectUnusedCode, getCodeCoverage, getGitHotspots

The bridge runs without any flags. No recipes, no automation, no dashboard — just the IDE-Claude connection.

Compatible IDEs: VS Code, Cursor, Windsurf, Google Antigravity. JetBrains IDEs via companion plugin.

Transport layers:

Tool modes:

Bridge-only docs: documents/platform-docs.md

🤖 Patchwork OS — Quick Start

npx patchwork-os@alpha patchwork-init

Sets up 5 local recipes, detects Ollama, and opens a terminal dashboard — under 90 seconds.

What it adds on top of the bridge

Patchwork OS is a local automation platform that watches your workspace for events, runs AI-powered recipes in response, and routes anything risky through an approval queue before it goes anywhere.

Think of it as a background agent that acts on your behalf — but asks before sending, writing, or modifying anything consequential.

• Test suite fails on CI → triage note in your inbox before you wake up
• Customer email arrives → draft reply in your voice, pending your approval
• Field-trip permission form flagged → reply drafted to the teacher, waiting for your nod

Recipes are plain YAML files. They declare a trigger (cron, file save, git commit, test run, webhook) and an action (run a prompt, write to inbox, call a connector). No code required. Share them like dotfiles.

Models are yours. Claude, GPT, Gemini, Grok, or local Ollama. Swap at any time. Nothing phones home.

Oversight is non-negotiable. Every write or external action lands in ~/.patchwork/inbox/ for approval. The web UI at http://localhost:3100 shows pending approvals, live sessions, recipe run history, and analytics.

Patchwork commands

# One-command setup: extension + CLAUDE.md + starter recipes
patchwork patchwork-init

# Explore
patchwork recipe list                      # installed recipes
patchwork recipe run daily-status         # run one now
patchwork recipe run morning-brief --local # run with local Ollama
patchwork tools list                      # browse 170+ tools
patchwork                                 # open terminal dashboard

# Web UI — bridge + extension watcher in tmux
patchwork start-all                       # then http://localhost:3100

Starter recipes

No external API keys needed for these:

Connectors (Linear, Sentry, Slack, Google Calendar, Intercom, HubSpot, Datadog, Stripe) require API keys and approval-gated writes.

Automation hooks

Event-driven hooks trigger Claude tasks automatically. Activate with --automation --automation-policy <path.json> --claude-driver subprocess.

Key hooks:

All hooks support inline prompts, named prompt references, and a minimum 5s cooldown. Full reference: documents/platform-docs.md → Automation Hooks

Architecture

patchwork-os (npm package)
│
├── claude-ide-bridge          ← run alone for bridge-only mode
│   ├── MCP server             170+ tools over WebSocket / HTTP / stdio
│   ├── VS Code extension      LSP, debugger, editor state, live diagnostics
│   ├── Git / GitHub           gitCommit, gitPush, githubCreatePR, …
│   ├── Terminal               runInTerminal, getTerminalOutput, …
│   └── Code quality           auditDependencies, detectUnusedCode, getCodeCoverage
│
└── patchwork                  ← run for full Patchwork OS layer
    ├── Recipe runner          YAML triggers → LLM prompt → action
    ├── Connectors             Linear, Sentry, Slack, Google Calendar, +
    ├── Orchestrator           Claude subprocess tasks, automation hooks
    ├── Oversight inbox        ~/.patchwork/inbox/ — approval queue
    └── Web dashboard          http://localhost:3100 — approvals, sessions, analytics

The npm package ships three CLI binaries that share the same code:

Use whichever fits your mental model.

Tool surface (v0.2.0-alpha.35)

170+ MCP tools across 15 categories. Highlights:

Full reference: documents/platform-docs.md

Plugin system

Extend the tool surface without forking the bridge.

# Scaffold a new plugin
patchwork gen-plugin-stub ./my-plugin --name "org/name" --prefix "myPrefix"

# Load at runtime
claude-ide-bridge --plugin ./my-plugin

Plugins register MCP tools in-process. Publish to npm with keyword claude-ide-bridge-plugin.

Full reference: documents/plugin-authoring.md

JetBrains plugin

Companion IntelliJ plugin (v1.0.0) on the JetBrains Marketplace. Covers 49 handlers: core tools, PSI-based LSP (goto, references, hover, rename, symbols, format), XDebugger integration, and code style tools.

Use the same bridge from VS Code and JetBrains IDEs simultaneously — IntelliJ IDEA, PyCharm, GoLand, WebStorm, and other IntelliJ-platform editors.

Source: intellij-plugin/

Remote deployment

Run headless on a VPS with full tool support via VS Code Remote-SSH.

claude-ide-bridge --bind 0.0.0.0 \
  --issuer-url https://your-domain.com \
  --fixed-token <uuid> \
  --vps

Systemd service and deploy scripts in deploy/. Full guide: docs/remote-access.md.

What's shipped

Install from source

git clone https://github.com/Oolab-labs/patchwork-os
cd patchwork-os
npm install && npm run build

# Pack first — do NOT use `npm install -g .`
# Symlink installs break the macOS LaunchAgent (EPERM at startup)
npm pack
npm install -g patchwork-os-*.tgz
patchwork patchwork-init

Documentation

License

MIT © Oolab Labs