cowork-harness
Scriptable, CI-friendly test harness that reproduces Claude Cowork's observable runtime contract closely enough to test the skills you write — across many scenarios, headless, in CI — without the (locked) Desktop app. It reproduces not just Cowork's behavior but its limitations: sealed filesystem, default-deny egress, MCP-only cross-boundary — so a green test means green in real Cowork.
Contents: Why it works · Fidelity tiers · Quick start · Session + scenario · Boundary · Discovery · Testing & CI/CD · Maintenance · Docs
Requirements at a glance
- Free demo (
replay): Node ≥ 20 — nothing else (no Docker, token, or Claude Desktop).
- Live tiers (
container default / microvm / hostloop): Docker (arm64) · Claude Desktop opened once (stages the agent — nothing is bundled) · a Claude token (real per-run cost; runs take minutes). The protocol tier skips Docker + the staged agent but still calls a real model, so it needs the token.
- Platform: best on macOS Apple Silicon; Windows is not supported for the live tiers (use the token-free
replay); sync and microvm are macOS-arm64 only. Full detail in Quick start → prerequisites.
New here? Read docs/boundary.md (the limitations model) and docs/session.md (the file you'll author).
What this is and isn't. This is an emulator of the contract, not the Desktop runtime. Cowork's real session control plane lives behind the Desktop renderer's IPC (per-build UUID + senderFrame origin checks) and the app ships with remote debugging disabled (verified: --remote-debugging-port opens no listener; Electron EnableNodeCliInspectArguments fuse is OFF). So you cannot drive the real Apple Virtualization.framework microVM from a script. What you can faithfully reproduce is everything that actually changes how a skill behaves: the same agent binary in cowork mode (CLAUDE_CODE_IS_COWORK=1 — there is no --cowork flag), the same mount layout, the same egress allowlist, and the same permission/question protocol. That's what this project does.
Why this works for skill testing
A skill's behavior under Cowork is determined by four things, all reproducible outside the VM:
| Dimension | What Cowork does | How we reproduce it | Fidelity |
|---|
| Agent | Spawns the staged in-VM agent claude-code-vm/<ver>/claude in cowork mode (CLAUDE_CODE_IS_COWORK=1 env — there is no --cowork flag) | Run the same pinned agent, bind-mounted from your Claude Desktop install's staged Linux/arm64 ELF (no npm path; override with COWORK_AGENT_BINARY) | High — same binary contract |
| Mounts | /sessions/<id>/mnt/{uploads,.projects/<id>,.local-plugins,.remote-plugins} | Recreate the same paths as bind mounts; skill-under-test discovered at the plugin mount, same as Cowork | High — same discovery path |
| Egress | gVisor netstack with a compiled domain allowlist (vmAllowedDomains() + coworkEgressAllowedHosts) | Default-deny egress proxy enforcing the synced allowlist | Med-High — allowlist-exact, transport-approximate |
| Permissions / questions | onToolPermissionRequest → respondToToolPermission; AskUserQuestion answered by the UI | The Agent SDK can_use_tool control protocol — the exact same channel — answered by your scenario script | High — same protocol Desktop uses |
