Patchwork OS

What is Patchwork OS?

Patchwork OS is a local-first personal AI runtime that runs on your machine, under your control. It combines an MCP bridge for Claude Code IDE integration with a full automation platform featuring YAML recipes, a delegation policy with an approval queue, durable trace memory, and OAuth—all with no vendor lock-in and no telemetry unless you opt in.

How to use Patchwork OS?

Install the npm package (npm install -g patchwork-os). For the Claude IDE Bridge run claude-ide-bridge and connect Claude Code with claude --ide. For the full Patchwork OS run patchwork init to scaffold configuration and start the dashboard at http://localhost:3200. A dashboard‑only mode requires no code editor—just npx patchwork-os@beta init then patchwork start.

Key features of Patchwork OS

• 177 built-in tools (LSP, git, terminal, debugger, files) plus hot-reloadable plugins
• YAML recipes triggered by cron, file save, git commit, test run, or webhook
• Delegation policy with three risk tiers and four‑source precedence
• Durable trace memory – every approval and recipe run is saved as JSONL
• OAuth with PKCE S256 and dynamic client registration for a private personal API
• Works natively on Windows, macOS, and Linux with no WSL required

Use cases of Patchwork OS

• Morning Brief: AI digest of Gmail, calendar, and tasks delivered to an inbox
• Automated CI triage – analyse test failures and write a report before you wake up
• Draft email replies in your voice pending human approval
• Run background agent workflows that ask before modifying anything sensitive
• Connect multiple AI clients (Claude Code, Gemini CLI, Grok Build) to the same runtime

FAQ from Patchwork OS

What are the runtime requirements for Patchwork OS?

Node.js 22+ is required. On macOS/Linux tmux is auto‑detected but the runtime falls back to background mode if absent. Windows is natively supported (no WSL needed) for the bridge and dashboard.

Where are my data, logs, and configuration stored?

All configuration, inbox files, and trace logs live in ~/.patchwork/. The trace memory is durable JSONL that you can bundle and back up with patchwork traces export.

Can I use Patchwork OS without Claude Code or any code editor?

Yes. The dashboard runs standalone as a Next.js app over HTTP. You can schedule YAML recipes, manage approvals, and read the AI inbox entirely from the browser—no editor required.

Does Patchwork OS phone home or send telemetry?

No. Nothing phones home unless you explicitly opt in to anonymous analytics. The runtime and all data stay on your machine.

How do I connect Gemini CLI or Grok Build to Patchwork OS?

Gemini CLI connects via Streamable HTTP with a Bearer token (use patchwork-os print-token). Grok Build connects via a stdio shim (claude-ide-bridge shim --workspace /path) or Streamable HTTP. See the README for exact configuration steps.