⭐ If this saves you a config file or a debug session, drop a star — it's the only signal I get that it's helping.

Patchwork OS is a local-first personal AI runtime: pluggable model providers, hot-reloadable tools, YAML recipes, a delegation policy with approval queue, and a durable trace memory — all running on your machine, all under your policy.

You decide which model. You decide which actions need a human nod. You own the credentials, the logs, and the deployment. Nothing phones home unless you opt in to anonymous analytics.

Five primitives, one runtime:

• Tools — 177 built-in (LSP, git, terminal, debugger, files) plus any plugin you write. Plugins hot-reload — Claude can author a tool mid-session and call it on the next turn. See Live Toolsmithing.
• Recipes — YAML automations triggered by cron, file save, git commit, test run, or webhook. Anything that can POST a JSON payload can fire a recipe.
• Delegation Policy — three risk tiers, four-source precedence (managed → project-local → project → user). Auto-approve safe, require approval for risky, block dangerous.
• Trace memory — every approval, every recipe run, every enrichment is durable JSONL. Past decisions are surfaced into future sessions automatically. Bundle and back up with patchwork traces export.
• OAuth — turn your runtime into a private personal API. PKCE S256, dynamic client registration, deployable on a VPS in minutes.

Why not [an MCP server / Zapier / a hosted assistant / a local agent framework]? See the comparison page for the honest tradeoff against each.

What does this look like in one diagram? See the architecture overview.

The same codebase ships two ways to use it. 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.

You do not need VS Code, Windsurf, Cursor, or Claude Code CLI to use the Patchwork dashboard.

The dashboard is a standalone Next.js app that communicates with the bridge over HTTP. No editor extension required.

Prereqs: Node.js 20+ · tmux on macOS/Linux (brew install tmux / apt install tmux) — auto-detected, falls back to background mode if absent. Windows: natively supported — no WSL required.

npx patchwork-os@beta init   # scaffolds ~/.patchwork and generates a dashboard login (no install needed)
patchwork start              # launches bridge + dashboard (auto-detects tmux; falls back to background mode if absent)

Open http://localhost:3200 — that's it. npx patchwork-os@beta init auto-generates a dashboard password and saves it to ~/.patchwork/.env — it prints the password at the end of setup, save it for your first login.

What you get: run and schedule YAML recipes, connect external services (Gmail, Calendar, Slack), review AI drafts in the approval queue, read your AI inbox — all from the browser. No coding required.

Want IDE features too? See Claude IDE Bridge — Quick Start below to add LSP, debugger, and editor tools on top.

Developers only — skip to Dashboard Only above if you just want the web dashboard.

Prerequisites: a supported code editor — VS Code, Cursor, Windsurf, or Google Antigravity (or JetBrains via the companion plugin) — plus Node.js 20+ and the Claude Code CLI. The bridge's LSP, debugger, and editor-state tools run through the editor extension; without one you're limited to the headless CLI subset.

# 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 177 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:

Connecting Gemini CLI:

# Get the auth token from the bridge's lock file
patchwork-os print-token

# Add the bridge as an MCP server
gemini mcp add patchwork http://127.0.0.1:<port>/mcp \
  --header "Authorization: Bearer <token>"

The bridge auto-responds to the GET probe Gemini sends before initializing, so it shows as Connected immediately.

Tool modes:

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

The bridge, VS Code extension, and full Patchwork OS orchestrator (patchwork start) all work natively on Windows — no WSL required. A PowerShell-native orchestrator is also available as npm run start-all:win. For architecture details, troubleshooting, and contribution patterns, see docs/windows.md.

• Node.js 20+ (from nodejs.org)
• VS Code, Cursor, or Windsurf
• Claude Code CLI
• PowerShell 5.1+ (built into Windows 10/11) or PowerShell 7+ (pwsh)

Open PowerShell or cmd.exe:

# 1. Install
npm install -g patchwork-os

# 2. Install the VS Code extension
claude-ide-bridge install-extension

# 3. Start the bridge (bash-free entry point)
npm run start:bridge
# or equivalently:
node "$(npm root -g)/patchwork-os/dist/index.js" --workspace .

# 4. Connect Claude Code (new terminal)
claude --ide

Type /ide in Claude Code to confirm the connection.

Two options — both work on Windows, macOS, and Linux:

# Option A: cross-platform Node.js orchestrator (recommended)
npm run start-all:node
npm run start-all:node -- --workspace C:\myproj --full --no-dashboard

# Option B: PowerShell-native orchestrator (Windows only, no Node wrapper overhead)
npm run start-all:win
npm run start-all:win -- -NoDashboard -Workspace C:\myproj -Full

Both start the bridge, wait for the lock file, launch claude --ide and remote-control, start the Next.js dashboard on http://localhost:3200, poll until it's ready, then open it in your default browser. The health monitor restarts the bridge automatically if it crashes, with exponential backoff.

# Node orchestrator options (--key value form)
npm run start-all:node -- --full               # all 177 tools
npm run start-all:node -- --no-dashboard       # skip dashboard
npm run start-all:node -- --dashboard-port 3300
npm run start-all:node -- --no-remote          # skip remote-control
npm run start-all:node -- --notify my-topic    # ntfy.sh push notifications

For full Patchwork OS functionality including orchestrator, recipes, and morning-brief, run everything inside WSL2 and install the VS Code Remote-WSL extension. The bridge extension loads on the WSL side automatically (extensionKind: ["workspace"]), giving full tool coverage.

npx patchwork-os@beta init

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

Get an AI digest of your Gmail, calendar, and tasks every morning — or on demand:

# First-time setup (connect Gmail + Google Calendar)
patchwork-os init
patchwork-os connections connect gmail
patchwork-os connections connect google-calendar

# Run it now
patchwork-os recipe run morning-brief

The brief lands in ~/.patchwork/inbox/ as a Markdown file. Open the dashboard (http://localhost:3200) to read it, approve any drafted replies, or let it auto-send at 08:00 via the built-in cron trigger.

No connectors yet? Run with --local using Ollama — it summarises your clipboard and last-touched files instead.

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 unless you opt in (see Telemetry).

Oversight is non-negotiable. Every write or external action lands in ~/.patchwork/inbox/ for approval. The web UI at http://localhost:3200 shows pending approvals, live sessions, recipe run history, and local analytics (the dashboard's analytics panel is computed entirely from on-disk logs — it does not transmit anything).

Grouped by what they do. Full list: patchwork --help.

Setup

npx patchwork-os@beta init                # one-command first-time setup (no install needed)
patchwork install-extension               # install the VS Code / Cursor / Windsurf extension
patchwork gen-claude-md                   # generate a starter CLAUDE.md for this workspace
patchwork gen-plugin-stub ./my-plugin --name "org/name" --prefix "myPrefix"

Runtime

patchwork start                           # bridge + dashboard (auto-detects tmux)
patchwork start-all                       # bridge + extension watcher in tmux
patchwork dashboard                       # launch dashboard standalone
patchwork shim                            # stdio shim for Claude Desktop
patchwork status                          # one-shot health check
patchwork print-token                     # auth token from the active lock file

Recipes & tasks

patchwork recipe list                     # installed recipes
patchwork recipe run daily-status         # run one now
patchwork recipe new my-recipe --interactive
patchwork start-task "<description>"      # enqueue a free-form Claude task
patchwork quick-task fixErrors            # context-aware preset task
patchwork continue-handoff                # resume from stored handoff note
patchwork suggest                         # AI-suggest a recipe for a goal

Ops & insight

patchwork halts --window overnight        # morning summary of recent recipe halts
patchwork judgments                       # review recent approval / decision traces
patchwork traces export                   # bundle durable trace memory for backup
patchwork launchd                         # macOS LaunchAgent management
patchwork notify <Event>                  # bridge ←→ Claude Code hook wiring

Safety

patchwork kill-switch engage              # stop all background automation immediately
patchwork kill-switch status              # is the kill-switch active?
patchwork kill-switch release             # resume automation
patchwork panic                           # alias for `kill-switch engage`

The package ships these in templates/recipes/. Recipes that need API keys are noted; the rest are zero-config.

Connectors available (all writes governed by your delegation policy): Slack, GitHub, Linear, Gmail, Google Calendar, Google Drive, Sentry, Notion, Confluence, Datadog, HubSpot, Intercom, Stripe, Zendesk, Jira, PagerDuty, Discord, Asana, GitLab.

Delegation policy presets (templates/policies/): five persona starters — conservative, developer, headless-CI, regulated-industry, personal-assistant. Copy one into ~/.patchwork/config.json and restart.

Webhook recipe starters (templates/recipes/webhook/): five webhook-triggered recipes — capture-thought, morning-brief (on-demand), meeting-prep, incident-intake, customer-escalation. Anything that can POST HTTP can drive these — iPhone Shortcut, Stream Deck, Home Assistant, NFC tag, monitoring tool.

Event-driven hooks trigger Claude tasks automatically. Activate with --automation --automation-policy <path.json> --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

Hand a task off to Claude's computer-use sandbox without losing IDE context. Run /mcp__bridge__cowork in a regular Claude chat to snapshot editor state, then open Cowork — it reads the handoff note for instant continuity. Cowork runs in an isolated git worktree. See docs/cowork.md.

Start the bridge with --issuer-url https://your-domain.com to expose a full OAuth 2.0 surface: PKCE S256, dynamic client registration (RFC 7591), /oauth/authorize approval page, opaque 24h access tokens. Connect claude.ai, Codex CLI, or any MCP client over Streamable HTTP. See docs/remote-access.md.

patchwork kill-switch engage (or the patchwork panic alias) halts all running automation, recipes, and orchestrator tasks immediately. patchwork kill-switch status reports state; release resumes. Designed for the moment you realise an agent is doing the wrong thing.

Bridge, VS Code extension, smoke harness, and CI are all green on native Windows — no WSL required. See Windows Quick Start above.

patchwork halts --window overnight prints a one-screen digest of recipe halts (categorised, 5 most recent reasons). Pair with patchwork judgments to review what Claude decided overnight before approving anything.

Browse the curated registry at github.com/patchworkos/recipes at /marketplace in the dashboard. One-click install if the bridge is running, with risk + connector preview before fetch.

Contributing a recipe? /marketplace/submit is a full in-app submission flow: starter YAML presets (manual / scheduled / webhook), live recipe.json manifest preview, auto-save draft in sessionStorage, lint via the bridge before submit, and a "Submit to GitHub" button that opens a prefilled create-file PR on the registry repo. GitHub auto-forks for users without push access — no extra accounts needed.

patchwork-os (npm package)
│
├── claude-ide-bridge          ← run alone for bridge-only mode
│   ├── MCP server             177 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:3200 — approvals, sessions, analytics

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

Use whichever fits your mental model.

177 MCP tools across 15 categories. Highlights:

Full reference: documents/platform-docs.md

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. With --plugin-watch, the bridge reloads them on save — Claude can write a tool during a session and use it on the next turn. See documents/live-toolsmithing.md for the worked walkthrough and examples/plugins/sqlite-library/ for a runnable example.

Publish to npm with keyword claude-ide-bridge-plugin for distribution.

Full reference: documents/plugin-authoring.md

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/

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.

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 init

Patchwork ships an opt-in anonymous usage summary. It is disabled by default — the bridge sends nothing unless you explicitly turn it on.

If you opt in, on bridge shutdown an aggregate summary is POSTed to https://analytics.claude-ide-bridge.dev/v1/usage:

• Total session count and total tool-call count (no per-call payloads)
• Tool name → call count + median/p95 latency, capped at the top-N tools
• Bridge version, Node version, OS family (darwin / linux / win32)
• A per-install random salt (regenerated at any time by deleting ~/.claude/ide/analytics-salt) used to coalesce repeated installs from the same machine without sending machine identifiers

What is never sent: workspace paths, file contents, prompts, tool arguments, tool output, project names, git history, credentials, IPs (transport-level only, dropped server-side), or anything from ~/.patchwork/.

How to opt in: set analyticsEnabled: true in the dashboard's Settings panel, or write {"enabled": true, "decidedAt": "<iso>"} to ~/.claude/ide/analytics.json (mode 0600).

How to opt out / stay out: do nothing. Default state is null (no preference) which behaves as opt-out. To explicitly opt out and silence future prompts, write {"enabled": false, ...} to the same file.

Source: src/analyticsSend.ts, src/analyticsAggregator.ts, src/analyticsPrefs.ts — endpoint is hardcoded (not runtime-configurable, by design, to prevent redirect attacks).

• Bugs & feature requests: GitHub Issues
• Questions & community: GitHub Discussions

MIT © Oolab Labs