---
title: Multi-Agent Project Review — Patchwork OS
version: 0.2.0-alpha.18
date: 2026-04-22
status: current-state snapshot
---

# Executive Summary

Patchwork OS (built on claude-ide-bridge) is in **strong shape**. `tsc --noEmit` is clean, `vitest` is **3437 / 3437 green across 250 test files (~72s)**, and the only "errors" reported by Biome are purely formatter diffs in two scratch files at the repo root plus one ternary-nesting cosmetic issue in `src/bridge.ts`. No functional regressions, no TODO/FIXME debt of substance (2 across all of `src/`). Primary risks are **code-size gravity** in a handful of monolith modules and **lint hygiene drift** (non-null assertions, stale suppressions). No P0 blockers.

| Area | Status | Verdict |
|---|---|---|
| TypeScript strictness | clean | ✅ |
| Tests | 3437 pass / 0 fail | ✅ |
| Lint errors | 8 (all formatter-only) | 🟡 cosmetic |
| Lint warnings | 56 | 🟡 |
| File-size ceiling | 8 files >1k LOC | 🟡 |
| Security posture | unchanged from v2.4 audit | ✅ |
| Dependency sanity | 9 runtime deps, all pinned ^ | ✅ |
| Docs vs reality | README matches recipe surface | ✅ |

---

# Agent 1 — Architecture & Structure

## Module map (top `src/*.ts` by LOC)

| File | LOC | Role |
|---|---|---|
| `server.ts` | 2221 | HTTP/WS server wiring, routes |
| `extensionClient.ts` | 2045 | VS Code extension ↔ bridge protocol |
| `index.ts` | 1981 | CLI entrypoint, flag parsing, bootstrap |
| `prompts.ts` | 1936 | Prompt templates for Claude driver |
| `bridge.ts` | 1927 | WS session mgmt, circuit breaker, dispatch |
| `automation.ts` | 1841 | Recipe/automation engine |
| `transport.ts` | 1590 | MCP JSON-RPC transport, AJV validation |
| `oauth.ts` | 1052 | Connector OAuth flows |

Total `src/*.ts` top-level: **23,810 LOC** across 53 files; `src/tools/` holds **131 tool implementation files** driving ~**167 tool registrations** via `src/tools/index.ts` (134 imports).

## Findings

- **Monolith pressure** — five files are **>1900 LOC**. Not urgent, but `server.ts`, `extensionClient.ts`, and `bridge.ts` are the three most frequently-touched files and will become merge-conflict magnets as contributors scale.
  - *Recommendation:* extract by responsibility: route handlers from `server.ts` into `src/routes/`, per-capability extension RPC shims from `extensionClient.ts` into `src/extensionRpc/`, circuit-breaker + pong-starvation logic from `bridge.ts` into `src/bridgeHealth.ts`.
- **`prompts.ts` (1936 LOC)** is almost entirely static strings. Splitting into `src/prompts/<name>.ts` would not change behavior and would make prompt diffs reviewable.
- **Tool registration** is centralized in `src/tools/index.ts` (946 LOC, 134 imports). This is *good* — single source of truth — but the file is past the comfortable read-in-one-scroll size. Consider grouping by capability (`registerLspTools`, `registerGitTools`, `registerDebugTools`, …) and composing them.
- **Boundary leak** — a handful of tool files import directly from `automation.ts`, `activityLog.ts`, `claudeOrchestrator.ts`. A thin `ToolContext` interface already exists in `src/tools/index.ts`; worth auditing tools that bypass it.
- **Package exports** (`package.json`) declare `./` and `./plugin` — both resolve to built `dist/*.js`. The `bin` field exposes three aliases (`patchwork`, `patchwork-os`, `claude-ide-bridge`) — confirm the `prepublishOnly` check (`--help | grep issuer-url`) still matches current help output.
- **Deploy surface** (`deploy/`) looks complete: nginx template, systemd unit + template, installer script, VPS bootstrap. No rot flagged.

---

# Agent 2 — Code Quality & Diagnostics

## TypeScript

`tsc --noEmit`: **0 errors**. Strict mode per `tsconfig.json`. ✅

## Biome

```
Checked 642 files
  8 errors   (all formatter-only, no lint rules)
 56 warnings
  6 infos
```

**Errors (formatter only — fix with `biome check --write .`):**
- `loop_test.mjs`, `save_trace.mjs` — scratch files at repo root; consider moving to `scripts/` or deleting.
- `.gemini/settings.json` — JSON formatter
- `src/bridge.ts:895` — nested ternary broken across lines; `biome format` rewrites it.
- `src/connectors/gmail.ts`, `src/connectors/googleCalendar.ts`, `src/drivers/gemini/index.ts` — formatter.
- `src/tools/__tests__/ctxSaveTrace.test.ts` — formatter.

**Warnings (by rule):**

| Rule | Count | Disposition |
|---|---|---|
| `style/noNonNullAssertion` | 38 | Most are `arr[0]!` patterns after length checks — acceptable but replaceable with `?? throw` helper. |
| `suppressions/unused` | 10 | Stale `// biome-ignore` lines — safe to delete. |
| `correctness/noUnusedVariables` | 6 | Likely dead refactor remnants. |
| `correctness/noUnusedImports` | 1 | Auto-fixable. |
| `suspicious/useBiomeIgnoreFolder` | 1 | `biome.json` config nit. |

**Infos (6):** all `style/useTemplate` — prefer template literals over `+` concat. Cosmetic.

## Code health

- TODO / FIXME in `src/`: **2** total (`createIssueFromAIComment.test.ts`, `nativeFallbacks.test.ts`). Exceptional.
- `noNonNullAssertion` hotspots: `src/ccPermissions.ts` (14), `src/tools/previewEdit.ts` (13), `src/tools/getDiffFromHandoff.ts` (4), `src/tools/__tests__/recentTracesDigest.test.ts` (4). Worth a focused pass.
- Error handling is consistent across tool handlers (AJV pre-validation in `transport.ts` catches schema violations before dispatch).

---

# Agent 3 — Test Coverage

- **250 test files / 3437 tests / 0 failures / 72.5s wall time.**
- Source `.ts` files: **513**; test `.ts` files: **218** (spanning `src/__tests__/` + per-module `__tests__/`). Ratio ≈ 1 test file per 2.4 source files — healthy for a project of this size.
- Smoke runners exist (`smoke-test.mjs`, `smoke-test-v2.mjs`, `scripts/smoke/run-all.sh`). Haven't executed them this pass; CI should be the source of truth.
- Property-based coverage is present (`fast-check` is in devDeps) — spot-checked in `src/fp/__tests__/`.

## Gaps worth closing

- **Coverage report not generated this pass** — `npm run test:coverage` was skipped to keep the review fast. Recommend wiring coverage deltas into CI so drift is visible per-PR.
- Tests exist for the engine layer (`automation.ts`, `claudeOrchestrator.ts`, `transport.ts`, `bridge.ts`) but the **8 largest files still lack line-level coverage goals**. Suggest a minimum 85% line-coverage gate on `src/bridge.ts`, `src/transport.ts`, `src/extensionClient.ts`.
- No visible tests for `deploy/` scripts or systemd template rendering. Low-value to add unless those templates change often.

---

# Agent 4 — API & Tool Surface

- **~167 tool registrations** dispatched from `src/tools/index.ts` (aggregating 131 tool modules). Earlier docs cite "124+"; the number has grown — update README/plugin.json claims before the next release.
- AJV structural validation on `inputSchema` happens in `transport.ts` before handler dispatch (per `project_remaining_todos.md` resolved entry 2026-03-13). Returns JSON-RPC `-32602` on violation. ✅
- `tools/list` cursor pagination (page size 50, base64 opaque cursor) is shipped — MCP SHOULD-compliant. ✅
- `organizeImports` has a native fallback (biome → prettier) when the VS Code extension is disconnected. Pattern is worth replicating: audit which tools still set `extensionRequired: true` and whether any have viable CLI fallbacks.
- **Documentation gap:** no machine-readable tool catalog in-repo. An auto-generated `docs/tools.md` (from `inputSchema.description`) would help both humans and Claude's tool selection.

---

# Agent 5 — Security & Deployment

## What's in place

- AJV schema validation on every incoming tool call (rejects unknown properties when schema sets `additionalProperties: false`).
- Plugin security hardening (round 2, 2026-03-16): entrypoint path traversal guard, checkpoint path injection, allowlist on `install-extension`, `realpathSync` re-check in `resources.ts`, prototype-pollution guard on elicitation, future-timestamp guard on checkpoints.
- `.env.vps.example` present, `.env` gitignored.
- `deploy/nginx-claude-bridge.conf.template`, `deploy/claude-ide-bridge@.service`, VPS bootstrap script all checked in.
- Auth token lives in `src/bridgeToken.ts` (~4.5 KB) — review separately if not recently audited.

## Open items to verify

- **Constant-time token comparison** — confirm `bridgeToken.ts` uses `crypto.timingSafeEqual` (not `===`). Not re-verified this pass.
- **WebSocket origin validation** — `bridge.ts` is 1927 LOC; confirm `verifyClient`/`handleUpgrade` enforces an allowlist on `Origin` header in multi-session mode.
- **Shell injection** — `runCommand` / `runInTerminal` tools: AJV schema validation helps, but any shell interpolation must use argv arrays (never string concat). Not re-verified this pass.
- **Systemd hardening** — confirm unit contains `NoNewPrivileges=yes`, `ProtectSystem=strict`, `PrivateTmp=yes`, `ProtectHome=read-only` or stricter.

---

# Synthesis — Prioritized Next Steps

## Quick wins (<1 hour total)

1. `npx biome check --write .` — kills all 8 formatter "errors" and 1 auto-fixable unused import.
2. Delete or move `loop_test.mjs` and `save_trace.mjs` from repo root into `scripts/dogfood/` (they're dogfooding harnesses, not products).
3. Remove the 10 stale `biome-ignore` suppressions flagged by `suppressions/unused`.
4. Update the "124+ tools" claim in README/plugin manifest to reflect the current ~167.

## P1 — pre-listing polish

5. Split `src/tools/index.ts` into capability bundles (`lsp`, `git`, `debug`, `context`, `connectors`) and compose in a thin root registrar.
6. Add coverage gate (≥85% lines on `bridge.ts`, `transport.ts`, `extensionClient.ts`) to CI.
7. Sweep `noNonNullAssertion` hotspots in `ccPermissions.ts` (14) and `previewEdit.ts` (13) — replace `!` with an `assertDefined(x, 'why')` helper so failures have actionable messages.
8. Re-verify the four security items under Agent 5 "Open items" and attach evidence (grep lines / test names) to the next release notes.

## P2 — post-listing structural work

9. Extract route handlers out of `src/server.ts` → `src/routes/*.ts`.
10. Split `src/prompts.ts` into `src/prompts/<name>.ts` (mechanical; large reviewability win).
11. Publish an auto-generated `docs/tools.md` from tool `inputSchema` descriptions; hook into `npm run build`.

## P3 — ecosystem

12. JetBrains plugin (tracked in `project_remaining_todos.md`).
13. Re-run `scripts/benchmark.mjs` after the next tool batch; store baseline in `docs/perf-baseline.md`.

---

# Appendix — Commands used

```bash
npx tsc --noEmit                                  # 0 errors
npx biome check . --max-diagnostics=300           # 8E / 56W / 6I
npm test -- --reporter=dot                        # 3437 passed
wc -l src/*.ts | sort -rn | head -20              # file-size census
grep -rE "TODO|FIXME" src --include="*.ts" | wc -l  # 2
```
