patchwork-os 0.2.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Oolab Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.bridge.md

@@ -0,0 +1,352 @@
+# Claude IDE Bridge
+
+[![npm version](https://img.shields.io/npm/v/claude-ide-bridge)](https://www.npmjs.com/package/claude-ide-bridge)
+[![CI](https://github.com/Oolab-labs/claude-ide-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/Oolab-labs/claude-ide-bridge/actions/workflows/ci.yml)
+[![Docker](https://img.shields.io/badge/docker-ghcr.io%2FOolab--labs%2Fclaude--ide--bridge-blue)](https://github.com/Oolab-labs/claude-ide-bridge/pkgs/container/claude-ide-bridge)
+[![License: MIT](https://img.shields.io/npm/l/claude-ide-bridge)](https://opensource.org/licenses/MIT)
+
+**MCP bridge giving Claude Code IDE superpowers: 141 tools for LSP, debugging, git, GitHub, terminals, and more.**
+
+A WebSocket bridge between Claude Code CLI and your VS Code extension. Claude sees what your IDE sees — live diagnostics, go-to-definition, call hierarchies, hover types, breakpoints, debugger state — and can act on it: edit files, run tests, commit, open PRs, all without you copy-pasting anything.
+
+Works locally, over SSH, in Docker, and on a VPS. Extension is optional — headless mode covers git, terminals, GitHub, and LSP via `typescript-language-server`.
+
+```
+Claude Code ──── bridge ──── VS Code extension ──── your editor state
+```
+
+> **See it work in 5 minutes:** save a broken file, Claude notices, diagnoses, proposes a fix — no prompt typed. [Self-healing quickstart →](./docs/self-healing-quickstart.md)
+
+https://github.com/user-attachments/assets/a81a8d11-2cc3-46f3-88ad-6a905a221a2c
+
+## Quick Start
+
+**Prerequisites:** [Claude Code CLI](https://claude.ai/code), Node.js ≥ 20
+
+```bash
+# 1. Install the bridge
+npm install -g claude-ide-bridge
+
+# 2. One-command setup (installs extension, writes CLAUDE.md, registers MCP server)
+cd /your/project
+claude-ide-bridge init
+
+# 3. Start the bridge (full tool set is the default — add --slim for IDE-only)
+claude-ide-bridge --watch
+
+# 4. Open Claude Code — bridge connects automatically
+claude --ide
+```
+
+> **Updating?** Use `npm install -g claude-ide-bridge@latest` — `npm update -g` may lag the registry cache after a new release.
+
+After `init`, type `/mcp` in Claude Code to confirm the bridge is connected. Type `/ide` to see open files, diagnostics, and editor state.
+
+> **One bridge per workspace.** Each project runs its own bridge instance on its own port. Start a separate `claude-ide-bridge --watch` in each directory.
+
+### Installing the VS Code extension separately
+
+```bash
+claude-ide-bridge install-extension
+```
+
+Or search **Claude IDE Bridge** in the VS Code / Cursor / Windsurf marketplace.
+
+---
+
+## Tool Categories
+
+| Category | Count | Example tools | Mode |
+|---|---|---|---|
+| LSP & Code Intelligence | 29 | `goToDefinition`, `findReferences`, `getCallHierarchy`, `getHover`, `explainSymbol` | S |
+| Debugging | 6 | `setDebugBreakpoints`, `startDebugging`, `evaluateInDebugger`, `getDebugState` | S |
+| Refactoring | 5 | `refactorAnalyze`, `refactorPreview`, `renameSymbol`, `refactorExtractFunction` | S |
+| Editor State | 8 | `getDiagnostics`, `getDocumentSymbols`, `getOpenEditors`, `contextBundle`, `watchDiagnostics` | S |
+| Git | 12 | `gitAdd`, `gitCommit`, `gitPush`, `getGitStatus`, `getGitDiff`, `gitCheckout`, `gitBlame` | F |
+| GitHub | 5 | `githubCreatePR`, `getPRTemplate`, `getGitHotspots` | F |
+| Files & Search | 10 | `findFiles`, `getFileTree`, `searchWorkspace`, `searchAndReplace`, `createFile`, `editText` | F |
+| Terminal & Shell | 6 | `runInTerminal`, `getTerminalOutput`, `runCommand`, `runVSCodeTask`, `listVSCodeTasks` | F |
+| Claude Orchestration | 5 | `runClaudeTask`, `listClaudeTasks`, `getClaudeTaskStatus`, `cancelClaudeTask` | F |
+| Quality & Analysis | 11 | `getCodeCoverage`, `auditDependencies`, `detectUnusedCode`, `generateTests`, `getSecurityAdvisories` | F |
+
+**S = slim (opt-in via `--slim`) · F = full mode (default)**
+
+---
+
+## Slim vs Full Mode
+
+The bridge starts in **full mode** by default (changed in v2.43.0) — all ~140 tools, covering LSP/debugger/refactoring plus git, GitHub, terminal, file tree, and orchestration.
+
+Pass `--slim` to restrict to the ~60 IDE-exclusive tools (LSP, debugger, editor state only) — useful when you want Claude to use its native Read/Write/Bash tools for everything else:
+
+```bash
+claude-ide-bridge --slim --watch
+```
+
+Or set permanently in `claude-ide-bridge.config.json`:
+
+```json
+{ "fullMode": false }
+```
+
+**Use `--slim` when:**
+- You prefer Claude's native Read/Write/Bash over bridge file/git/HTTP tools
+- Running in a locked-down environment and want to minimize exposed surface
+- You only need LSP navigation, debugger, and editor state signal
+
+The `--full` flag is retained as a no-op opt-in for backward compatibility.
+
+---
+
+## Usage Examples
+
+### Find every caller of a function
+```
+"Show me everything that calls processPayment()"
+```
+Claude runs `getCallHierarchy` — returns the full incoming call tree with file paths and line numbers, no grep required.
+
+### Fix all type errors in the workspace
+```
+"Fix the TypeScript errors in src/api/"
+```
+Claude calls `getDiagnostics` to get live compiler errors, then `editText` to patch each one. No build step needed — diagnostics are live from the language server.
+
+### Create a PR from the current branch
+```
+"Push my branch and open a PR against main"
+```
+Claude calls `gitPush`, then `githubCreatePR` — picks up your repo's PR template automatically and pre-fills it from recent commits.
+
+### Set a breakpoint and inspect a variable
+```
+"Break on line 42 of auth.ts and tell me what token contains"
+```
+Claude calls `setDebugBreakpoints`, `startDebugging`, then `evaluateInDebugger` — real debugger evaluation, not console.log guessing.
+
+### Refactor a symbol safely
+```
+"Rename UserService to AuthService everywhere"
+```
+Claude calls `refactorAnalyze` (checks blast radius and risk), `refactorPreview` (shows every edit before touching a file), then `renameSymbol` — language-server rename, not find-and-replace.
+
+---
+
+## Deployment Options
+
+### Local (VS Code / Cursor / Windsurf)
+Standard setup. Extension connects automatically. Full LSP, debugger, and editor state available.
+
+### Remote SSH
+VS Code Remote-SSH and Cursor SSH load the extension on the VPS side (`extensionKind: ["workspace"]`). Start the bridge on the remote machine. All ~140 tools work over SSH.
+
+```bash
+# On the remote machine
+claude-ide-bridge --watch --bind 0.0.0.0
+```
+
+### VPS + systemd
+Persistent bridge with automatic restarts, fixed auth token, and optional OAuth 2.0 for remote MCP clients (claude.ai, Codex CLI).
+
+```bash
+# Full provisioning
+bash deploy/bootstrap-new-vps.sh
+
+# Or just the service
+bash deploy/install-vps-service.sh
+```
+
+See [deploy/README.md](deploy/README.md) and [docs/remote-access.md](docs/remote-access.md).
+
+### Docker
+```bash
+docker run -p 3284:3284 ghcr.io/oolab-labs/claude-ide-bridge:latest --bind 0.0.0.0
+```
+
+Or with Compose:
+```bash
+docker compose up
+```
+
+Headless image includes `typescript-language-server` and `universal-ctags` for LSP and symbol search without VS Code. See [documents/headless-quickstart.md](documents/headless-quickstart.md).
+
+### Launch tasks from a terminal (headless parity)
+
+The sidebar's quick-task buttons also work from the CLI — same context-gathering, same prompt-building, same dispatch path:
+
+```bash
+# 7 presets: fixErrors · refactorFile · addTests · explainCode · optimizePerf · runTests · resumeLastCancelled
+claude-ide-bridge quick-task fix-errors
+claude-ide-bridge quick-task add-tests --json
+
+# free-form description (Claude gathers its own context)
+claude-ide-bridge start-task "Refactor the auth module for clarity, keep behaviour identical"
+
+# resume prior session from handoff note
+claude-ide-bridge continue-handoff
+```
+
+Requires `--claude-driver subprocess` on the running bridge. All three subcommands accept `--json`, `--port`, `--source`. Enforces a 5s bridge-global cooldown per preset (shared with the sidebar).
+
+---
+
+## Automation Hooks
+
+Event-driven hooks that trigger Claude tasks automatically — no polling, no manual invocation.
+
+```json
+{
+  "hooks": [
+    {
+      "event": "onDiagnosticsError",
+      "prompt": "Fix the type error in {{file}}: {{diagnostics}}",
+      "cooldownMs": 30000
+    },
+    {
+      "event": "onFileSave",
+      "patterns": ["src/**/*.ts"],
+      "prompt": "Run tests for {{file}} and fix any failures"
+    },
+    {
+      "event": "onGitCommit",
+      "prompt": "Review commit {{hash}}: {{message}}"
+    }
+  ]
+}
+```
+
+Start with:
+```bash
+claude-ide-bridge --watch --automation --automation-policy ./policy.json --claude-driver subprocess
+```
+
+**18 hook events:** `onFileSave`, `onFileChanged`, `onDiagnosticsError`, `onDiagnosticsCleared`, `onGitCommit`, `onGitPush`, `onGitPull`, `onBranchCheckout`, `onPullRequest`, `onTestRun`, `onTestPassAfterFailure`, `onPostCompact`, `onInstructionsLoaded`, `onTaskCreated`, `onTaskSuccess`, `onPermissionDenied`, `onCwdChanged`, `onDebugSessionEnd`
+
+All hooks support `cooldownMs` (min 5s), `promptName`/`promptArgs` for named prompts, and `when` conditions (`minDiagnosticCount`, `testRunnerLastStatus`). See [docs/automation.md](docs/automation.md).
+
+---
+
+## Plugin System
+
+Extend the bridge with custom MCP tools without forking. Plugins load in-process alongside built-in tools and support hot reload.
+
+```bash
+# Scaffold a new plugin
+claude-ide-bridge gen-plugin-stub ./my-plugin --name "org/my-plugin" --prefix "myPrefix"
+
+# Load it
+claude-ide-bridge --watch --plugin ./my-plugin --plugin-watch
+```
+
+Publish to npm with keyword `claude-ide-bridge-plugin` — users install by package name:
+
+```bash
+claude-ide-bridge --plugin claude-ide-bridge-my-plugin
+```
+
+See [documents/plugin-authoring.md](documents/plugin-authoring.md) for the full manifest schema and entrypoint API.
+
+---
+
+## Companion Marketplace
+
+Install curated companion MCP servers directly into your Claude Desktop config:
+
+```bash
+claude-ide-bridge marketplace list
+claude-ide-bridge marketplace search memory
+claude-ide-bridge install claude-mem
+```
+
+`install` merges the companion into `mcpServers` in your Claude Desktop config atomically and idempotently — no manual JSON editing.
+
+---
+
+## CLI Reference
+
+| Command | What it does |
+|---|---|
+| `claude-ide-bridge init` | One-command setup: install extension + write CLAUDE.md + register MCP server |
+| `claude-ide-bridge --watch` | Start bridge with auto-restart on crash (2s → 30s backoff) |
+| `claude-ide-bridge --slim` | Restrict to ~60 IDE-exclusive tools (default: ~140 full tools) |
+| `claude-ide-bridge install-extension` | Install companion VS Code extension |
+| `claude-ide-bridge gen-claude-md --write` | Add bridge section to existing CLAUDE.md |
+| `claude-ide-bridge print-token` | Print auth token from active lock file |
+| `claude-ide-bridge gen-plugin-stub <dir>` | Scaffold a new plugin |
+| `claude-ide-bridge marketplace list` | List available companion servers |
+| `claude-ide-bridge install <companion>` | Install companion into Claude Desktop config |
+| `claude-ide-bridge notify <Event>` | Post a hook event to a running bridge (for CC hook wiring) |
+| `claude-ide-bridge quick-task <preset>` | Launch a context-aware Claude task from a preset (headless parity with the sidebar) |
+| `claude-ide-bridge start-task "<description>"` | Enqueue a free-form Claude task with workspace context |
+| `claude-ide-bridge continue-handoff` | Resume prior session using the stored handoff note |
+| `claude-ide-bridge start-all` | Launch tmux session with bridge + extension watcher |
+
+**Key flags:**
+
+| Flag | Default | Description |
+|---|---|---|
+| `--slim` | off | Restrict to IDE-exclusive tools (default: full, ~140 tools) |
+| `--full` | on | No-op (retained for backward compat — full is the default since v2.43.0) |
+| `--watch` | off | Auto-restart on crash |
+| `--bind <host>` | `127.0.0.1` | Bind address (`0.0.0.0` for remote access) |
+| `--port <n>` | auto | Port (auto-detected from lock files) |
+| `--fixed-token <uuid>` | — | Stable auth token across restarts |
+| `--automation` | off | Enable automation hooks |
+| `--automation-policy <path>` | — | Path to policy JSON |
+| `--claude-driver subprocess` | none | Enable Claude subprocess orchestration |
+| `--plugin <path>` | — | Load a plugin (repeatable) |
+| `--plugin-watch` | off | Hot-reload plugins on change |
+| `--issuer-url <url>` | — | Activate OAuth 2.0 mode |
+| `--cors-origin <origin>` | — | Add CORS origin (repeatable) |
+| `--vps` | off | Expand command allowlist for VPS use |
+| `--grace-period <ms>` | 120000 | Session preservation window across disconnects |
+
+---
+
+## Documentation
+
+| File | Description |
+|---|---|
+| [ARCHITECTURE.md](ARCHITECTURE.md) | System topology, request lifecycle, component map, design decisions |
+| [documents/platform-docs.md](documents/platform-docs.md) | Full tool reference — all 141 tools with parameters and examples |
+| [documents/prompts-reference.md](documents/prompts-reference.md) | All MCP prompts (31 prompts, 12 plugin skills, 4 subagents) |
+| [docs/automation.md](docs/automation.md) | Automation hooks reference — all 18 events, policy schema, condition filters |
+| [docs/troubleshooting.md](docs/troubleshooting.md) | Diagnostics, common errors, and fixes |
+| [docs/remote-access.md](docs/remote-access.md) | VPS setup, OAuth 2.0, nginx/Caddy reverse proxy |
+| [documents/headless-quickstart.md](documents/headless-quickstart.md) | CI, Docker, server use without VS Code |
+| [docs/cowork.md](docs/cowork.md) | Computer-use (Cowork) workflow and git worktree setup — **MCP bridge tools unavailable inside Cowork** |
+| [docs/multi-ide.md](docs/multi-ide.md) | Multiple sessions and parallel editor instances |
+| [docs/migration.md](docs/migration.md) | Upgrade guide between major versions |
+| [documents/plugin-authoring.md](documents/plugin-authoring.md) | Plugin manifest schema, entrypoint API, distribution |
+| [documents/styleguide.md](documents/styleguide.md) | Code conventions, tool factory pattern, output formats |
+| [docs/adr/](docs/adr/) | Architecture Decision Records |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Contributor guide, build setup, test requirements |
+| [deploy/README.md](deploy/README.md) | VPS provisioning and systemd service scripts |
+
+---
+
+## Requirements
+
+- **Node.js ≥ 20** (bridge)
+- **VS Code, Cursor, or Windsurf** — optional. Headless mode covers git, terminals, GitHub, and LSP via `typescript-language-server`. Extension required for debugger, editor decorations, and live editor state.
+- **Claude Code CLI** — for local use. Remote MCP clients (claude.ai, Codex CLI) work via Streamable HTTP transport with OAuth 2.0.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## Contributing
+
+Bug reports and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+When reporting a bug, include the output of:
+```bash
+claude-ide-bridge print-token   # confirms bridge is running
+# then in Claude: call getBridgeStatus
+```
+
+Per the project's bug fix protocol: a reproducing test must exist before a fix lands.

package/README.md

@@ -0,0 +1,72 @@
+# Patchwork OS
+
+**AI that works while you're away. Runs on your machine. Doesn't lock you in.**
+
+Most AI assistants wait for you to type. Patchwork OS does the opposite: it watches for things that matter, does the work, and hands you a summary when you're ready.
+
+- **A parent's morning.** School emails sorted, the field-trip form flagged, a reply drafted to the teacher — done before the first coffee. You approve, it sends.
+- **A developer's overnight.** Tests run on every push, flaky ones quarantined, a clean PR opened against the failing build. You wake up to a passing CI and a short note on what changed.
+- **A small business's inbox.** New customer questions triaged, invoices matched to orders, three follow-ups drafted in your voice. Nothing sends without your nod.
+
+**How it works**
+
+- **Recipes** — plain YAML files describe what to watch for and what to do. Share them like dotfiles. No code required.
+- **Your models, your keys** — Claude, GPT, Gemini, Grok, or local Ollama. Swap anytime. Nothing phones home.
+- **Oversight you actually use** — a dashboard on your phone approves or rejects anything risky before it happens.
+
+Read the founding essay: [NARRATIVE.md](./NARRATIVE.md) · Full docs below.
+
+> Status: **Phase 0 — Foundation** (alpha, not yet published). Open source (MIT). Built on the [Claude IDE Bridge](./README.bridge.md).
+
+## Why
+
+Existing AI assistants answer questions. Patchwork OS *does things* while
+you're at your kid's soccer game or asleep:
+
+- **Multi-model from day one** — Claude, OpenAI, Gemini, Grok, local LLMs (Ollama)
+- **Drag-and-drop recipes** — YAML automation anyone can write
+- **Oversight dashboard** — approve/reject high-risk actions from phone
+- **Proven core** — 2,725+ tests, real-time IDE context, 170 built-in tools
+- **100% MIT**
+
+## Quick start (alpha)
+
+```bash
+npm install && npm run build
+node dist/index.js --model claude --full
+```
+
+Config lives at `~/.patchwork/config.json`. See [`config.schema.json`](./config.schema.json).
+
+## Roadmap
+
+| Phase | Name | Status |
+|---|---|---|
+| 0 | Foundation — rename, config, ModelAdapter | **in progress** |
+| 1 | Multi-model + Dashboard MVP | planned |
+| 2 | Recipe System + non-code workflows | planned |
+| 3 | Security + headless / mobile | planned |
+| 4 | Community + ecosystem | planned |
+| 5 | Optional hosted tier | year 2 |
+
+Full plan: `../Patchwork_OS_Plan_and_Roadmap.docx`.
+
+## Architecture
+
+Patchwork OS **extends** the Claude IDE Bridge, it does not replace it. The
+bridge's MCP server, automation hooks, orchestrator, plugin system, and tool
+library are the substrate. Patchwork adds:
+
+1. `src/adapters/` — `ModelAdapter` interface + per-provider implementations
+2. `src/recipes/` — YAML recipe parser → existing automation DSL *(planned)*
+3. `dashboard/` — Next.js oversight UI *(planned)*
+
+For the underlying bridge docs see [README.bridge.md](./README.bridge.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT © Oolab Labs.

package/deploy/README.md

@@ -0,0 +1,172 @@
+# Deploy
+
+Production VPS deployment files for claude-ide-bridge.
+
+> **Deployment targets:** The **systemd + nginx** path (this directory) is the
+> production-supported deployment for VPS/remote use. A `Dockerfile` and
+> `docker-compose.yml` exist in the repo root as an alternative for
+> containerised environments, but are not actively tested against the systemd
+> config — if you use Docker, treat it as a community-supported path and keep
+> it in sync with any service config changes.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `bootstrap-new-vps.sh` | **Full fresh-server setup** — Node.js, clone, build, user, firewall, systemd, nginx, Certbot |
+| `install-vps-service.sh` | **Idempotent updater** — re-installs service + nginx after `git pull` on an existing server |
+| `nginx-claude-bridge.conf.template` | nginx config reference (domain + port injected by scripts) |
+| `claude-ide-bridge.service.template` | systemd unit reference (paths + user injected by scripts) |
+| `claude-ide-bridge@.service` | Template unit for multi-user demo instances (alternate pattern) |
+| `ecosystem.config.js.example` | PM2 ecosystem config template (alternative to systemd) |
+
+## First-time setup (new VPS)
+
+```bash
+# Option A: run remotely on fresh server
+DOMAIN=bridge.example.com bash <(curl -fsSL https://raw.githubusercontent.com/Oolab-labs/claude-ide-bridge/main/deploy/bootstrap-new-vps.sh)
+
+# Option B: after cloning the repo
+DOMAIN=bridge.example.com bash deploy/bootstrap-new-vps.sh
+```
+
+The bootstrap script handles everything end-to-end:
+1. Installs Node.js 20, nginx, certbot
+2. Creates a dedicated `claude-bridge` system user (non-root)
+3. Clones the repo to `/opt/claude-ide-bridge`
+4. Runs `npm ci && npm run build`
+5. Generates `.env.vps` with a random auth token
+6. Opens ports 80/443 in ufw
+7. Installs and enables the systemd service
+8. Writes the nginx config with your domain injected
+9. Runs Certbot for HTTPS
+10. Starts the bridge and confirms it's healthy
+
+**Required:** `DOMAIN` env var pointing to a subdomain that resolves to your VPS IP.
+
+**Optional overrides:**
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `REPO_URL` | GitHub upstream | Git repo to clone |
+| `INSTALL_DIR` | `/opt/claude-ide-bridge` | Where to install |
+| `SERVICE_USER` | `claude-bridge` | System user to run as |
+| `PORT` | `9000` | Bridge listen port |
+| `BRANCH` | `main` | Git branch |
+| `SKIP_CERTBOT` | `0` | Set to `1` to skip TLS (DNS not ready) |
+
+## Updating an existing server
+
+```bash
+cd /opt/claude-ide-bridge   # or wherever INSTALL_DIR is
+git pull
+npm ci
+npm run build
+bash deploy/install-vps-service.sh
+```
+
+`install-vps-service.sh` re-generates the systemd unit and nginx config from the current state of `.env.vps`, then restarts the service automatically. It auto-detects the domain and service user from the existing installation — no config needed.
+
+## Day-to-day management
+
+```bash
+# View live logs
+journalctl -u claude-ide-bridge -f
+
+# Check status
+systemctl status claude-ide-bridge
+
+# Restart after code change
+npm run build && systemctl restart claude-ide-bridge
+
+# Stop (won't restart until manually started)
+systemctl stop claude-ide-bridge
+```
+
+## Using PM2 instead of systemd
+
+PM2 is a simpler alternative when you're running as root, already have PM2 installed, or prefer not to configure systemd manually.
+
+> **Important:** The bridge picks a **random port** by default. The port in your PM2 start command **must match** the port in your nginx `proxy_pass` directive, or every restart will cause a 502 Bad Gateway.
+
+### Quick start with PM2
+
+```bash
+# Replace 4748 and YOUR_TOKEN_HERE with your nginx proxy_pass port and auth token
+pm2 delete claude-bridge 2>/dev/null || true
+pm2 start /root/claude-ide-bridge/dist/index.js \
+  --name claude-bridge \
+  -- --port 4748 --bind 0.0.0.0 --vps --fixed-token YOUR_TOKEN_HERE
+pm2 save
+```
+
+Retrieve your token anytime:
+```bash
+cat ~/.claude/ide/*.lock | node -e "const d=require('fs').readFileSync('/dev/stdin','utf8').trim(); console.log(JSON.parse(d).authToken)"
+# or if you have a .env.vps:
+grep FIXED_TOKEN /root/claude-ide-bridge/.env.vps
+```
+
+### Persist across reboots
+
+```bash
+# Generate and run the startup command PM2 prints
+pm2 startup
+# (run the command it outputs, then:)
+pm2 save
+```
+
+### Using an ecosystem file
+
+For repeatable deployments, use the included example:
+
+```bash
+cp deploy/ecosystem.config.js.example ecosystem.config.js
+# Edit ecosystem.config.js: set cwd, port, and fixed-token
+pm2 start ecosystem.config.js
+pm2 save
+```
+
+### Day-to-day management with PM2
+
+```bash
+# View live logs
+pm2 logs claude-bridge
+
+# Check status
+pm2 status
+
+# Restart after code change
+npm run build && pm2 restart claude-bridge
+
+# Stop
+pm2 stop claude-bridge
+```
+
+## MCP endpoint
+
+```
+https://<your-domain>/mcp
+```
+
+Use in `.mcp.json` for Claude Desktop, claude.ai Custom Connectors, or any remote MCP client:
+
+```json
+{
+  "mcpServers": {
+    "claude-ide-bridge": {
+      "type": "http",
+      "url": "https://your-domain/mcp",
+      "headers": {
+        "Authorization": "Bearer ${BRIDGE_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+Set `BRIDGE_TOKEN` in your shell profile. Retrieve the token anytime:
+
+```bash
+grep FIXED_TOKEN /opt/claude-ide-bridge/.env.vps
+```