Patchwork OS

Your personal AI runtime, local-first.

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.

Five primitives, one runtime:

• Tools — 170+ 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.

🔌 Claude IDE Bridge — Quick Start

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 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@beta patchwork-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 patchwork-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.

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 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:3200

Starter recipes

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.

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:3200 — 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-beta.0)

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

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