Patchwork OS

Your personal AI runtime, local-first.

⭐ 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.

	What you get	Install	Best for
🔌 Claude IDE Bridge	MCP bridge connecting Claude Code to your IDE. 177 tools — diagnostics, LSP, debugger, terminal, git, GitHub, file ops.	npm i -g patchwork-os then run claude-ide-bridge	Anyone who wants Claude Code to see and act on their editor state
🤖 Patchwork OS	Everything in the bridge plus YAML recipes, approval queue, oversight dashboard, mobile push approvals, multi-model providers, JetBrains companion.	Same package, run patchwork init	Power users running automation, agent workflows, or background tasks

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

---

Dashboard Only — No Code Editor Required

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.

---

🔌 Claude IDE Bridge — Quick Start

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:

Client	Protocol
Claude Code CLI	WebSocket ws://127.0.0.1:<port>
Claude Desktop	stdio shim → WebSocket
Gemini CLI, Codex CLI, claude.ai	Streamable HTTP + Bearer token

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:

Mode	Tools	When to use
Full (default)	177	All git, GitHub, terminal, file ops, orchestration
Slim (--slim)	~60	LSP + debugger + editor state only

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

---

🪟 Windows Quick Start

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.

Prerequisites

• 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)

Bridge-only (recommended starting point)

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.

Full orchestrator (bridge + Claude + dashboard)

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

Known limitations on native Windows

Feature	Status
Bridge + extension (LSP, debugger, editor state)	✅ Full support
npm run start:bridge	✅ Supported
npm run start-all:node (Node.js orchestrator)	✅ Supported — cross-platform
npm run start-all:win (PS1 orchestrator)	✅ Supported — Windows-native
Dashboard (http://localhost:3200)	✅ Opens automatically
patchwork start / npm run start-all	⚠️ Requires WSL2 or Git Bash (uses bash + tmux)
npm run remote:node	✅ Supported — cross-platform Node auto-restart wrapper
npm run remote / npm run vps	⚠️ Requires WSL2 or Git Bash
Screenshot capture (standalone bridge)	⚠️ Not yet supported; extension screenshot works via VS Code
Credential storage	✅ Uses DPAPI (Windows Data Protection API) via PowerShell

WSL2 alternative

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.

---

🤖 Patchwork OS — Quick Start

npx patchwork-os@beta init

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

☀️ Morning Brief — the hero workflow

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.

---

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 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).

Patchwork commands

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`

Starter recipes

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

Recipe	Trigger	What it does	Needs
ambient-journal	git commit	Appends one line to ~/.patchwork/journal/	—
daily-status	cron 08:00	Morning brief from yesterday's commits	—
lint-on-save	file save	Surfaces new TS/JS diagnostics to inbox	—
stale-branches	cron weekly	Lists branches older than 30 days	—
watch-failing-tests	test run	Drops triage note to inbox on failure	—
project-health-check	manual	Snapshot of repo health + flagged risks	—
ctx-loop-test	manual	Smoke test for context-platform end-to-end	—
morning-brief	cron 08:00	Gmail + Linear + Slack + Calendar digest	Gmail, Linear, Slack, Google Calendar
morning-brief-slack	cron 08:00	Same brief but only posts to Slack	Linear, Slack
gmail-health-check	manual	Verify Gmail connector + token state	Gmail
inbox-triage	manual	Triage Gmail unread → suggest archive/reply	Gmail
sentry-to-linear	manual	Sentry issue → Linear ticket (one-shot)	Sentry, Linear

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.

Automation hooks

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

Key hooks:

Hook	Fires when
onFileSave	Matching files saved
onDiagnosticsStateChange	Errors appear or clear
onRecipeSave	Any .yaml/.yml saved — runs preflight
onGitCommit / onGitPush / onGitPull	Git tools succeed
onTestRun	Test run completes (filter: any/failure/pass-after-fail)
onBranchCheckout	After branch switch
onPullRequest	After githubCreatePR succeeds
onCompaction	Before/after Claude context compaction
onTaskCreated / onTaskSuccess	Orchestrator task lifecycle

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

---

More features

🖥️ Cowork (computer-use handoff)

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.

🔐 OAuth 2.0 — turn your runtime into a personal API

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.

🛑 Kill-switch — stop everything, now

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.

🪟 Native Windows support

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

☀️ Morning summary

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.

🛒 Recipe marketplace — install + submit from the dashboard

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.

---

Architecture

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:

Binary	Default behavior
claude-ide-bridge	Bridge only — no automation, no recipe runner, no dashboard
patchwork	Full Patchwork OS — automation + recipes + dashboard
patchwork-os	Alias for patchwork

Use whichever fits your mental model.

---

Tool surface

177 MCP tools across 15 categories. Highlights:

Category	Tools
LSP / Code Intelligence	getDiagnostics, goToDefinition, findReferences, getCallHierarchy, renameSymbol, refactorAnalyze, explainSymbol, … (37 tools)
Git	getGitStatus, getGitDiff, gitCommit, gitPush, gitCheckout, gitBlame, … (16 tools)
GitHub	githubCreatePR, githubListPRs, githubCreateIssue, githubPostPRReview, … (13 tools)
Terminal	runInTerminal, createTerminal, getTerminalOutput, waitForTerminalOutput
File Operations	editText, searchAndReplace, searchWorkspace, findFiles, getFileTree, …
Debugger	setDebugBreakpoints, startDebugging, evaluateInDebugger
Orchestrator	runClaudeTask, listClaudeTasks, getClaudeTaskStatus
Context Platform	ctxGetTaskContext, ctxQueryTraces, ctxSaveTrace, enrichStackTrace

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. 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

---

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

Feature	Status
177 MCP tools (LSP, git, tests, debugger, diagnostics)	shipped
VS Code / Cursor / Windsurf / Antigravity extension	shipped
JetBrains plugin (49 handlers)	shipped
patchwork init — one-command setup	shipped
Terminal dashboard	shipped
Web oversight UI (approvals, sessions, recipes)	shipped
Recipe runner (YAML, cron, manual, webhook)	shipped
Multi-provider LLM (Claude, Gemini, OpenAI, Grok, Ollama)	shipped
Connectors: Linear, Sentry, Slack, Google Calendar, Intercom, HubSpot, Datadog, Stripe	shipped
Cross-session memory (traces, handoff notes)	shipped
Mobile oversight PWA (push approvals)	shipped
Community recipe bundles (patchwork recipe install github:<org>/<repo>)	shipped
Community recipe registry / discovery UI	TBD

---

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 init

---

Telemetry

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).

---

Documentation

Doc	Contents
documents/platform-docs.md	Full tool reference (177 tools), automation hooks, connectors
documents/prompts-reference.md	All 36 MCP prompts
documents/styleguide.md	Code conventions, UI patterns
documents/roadmap.md	Development direction
documents/data-reference.md	Data flows, state management, protocol details
documents/plugin-authoring.md	Plugin manifest schema, entrypoint API, distribution
documents/live-toolsmithing.md	Write tools while the AI is using them — hot-reload narrative + worked example
documents/triggers.md	Anything Can Trigger Your AI — iPhone Shortcuts, Stream Deck, Home Assistant, curl, GitHub Actions
documents/speculative-refactoring.md	Stage multi-file edits, review the diff, commit or discard — honest about commit-phase semantics
documents/architecture.md	One-page architecture diagram + how to read it
documents/comparison.md	Patchwork vs MCP server / Zapier / hosted assistants / agent frameworks — honest tradeoffs
docs/adr/	Architecture Decision Records
docs/remote-access.md	VPS deployment guide

---

Support

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

---

License

MIT © Oolab Labs