Thesis: Every agent cockpit — Orca, Emdash, Conductor, Cursor, Claude Code — creates worktrees and watches agents. None of them makes the worktree runnable, and none of them lets you see the work running. v2 made workz the environment engine. v3 makes it the runtime layer: the thing that starts the app, hands you a URL, and tells you it's healthy.
One-liner: Your agent creates the worktree. workz makes it run — and gives you a URL to check the work.
Status: drafted 2026-07-27, after a landscape survey + the v0.9–v0.14 execution of V2.md.
Supersedes nothing in V2.md — the hook-first, environment-engine positioning still holds. This
extends it one layer up the stack.
V2.md's build list is essentially complete: the strip (fleet/serve/TUI, −4 heavy deps), hook
mode, workz hook <host>, doctor --fix, config v2 (additive keys + [sync.overrides]), the
init wizard, isolation hardening, MCP retarget. Then three releases past the plan: 0.12
teardown/reap, 0.13 CoW reflink deps, 0.14 named services + docker-pg fallback + env-diff.
V2's success metric was "issues filed > 0" — zero issues meant zero real users. That metric has now been met, and it changed the product:
- jacob-carlborg filed 9 issues in three weeks, every one reproducible and correct, from
running workz across several Rails repos with Claude Code. They exposed real defects:
--aibroke terminals (#11), hooks had no context (#12),clean --mergedwas a structural no-op (#22),doneorphaned DBs when the host deleted the worktree (#23), a bad config value silently discarded the whole file (#21),base_portwas a dead key (#24), and same-named worktrees across repos shared one database (#28 — data-loss-adjacent). - The
workz hook clauderecipe never worked (#18): Claude Code'sWorktreeCreatehook replaces worktree creation. Now fixed natively (workz claude-hook, #19). - Nicolas Ha installed it off a Slack post and reported: "works well but wasn't designed for monorepos."
Read: the environment engine is real and used, but its edges were untested until someone leaned on it. The remaining open issue is #16 (native multi-database config).
The cockpit layer is crowded and funded.
| Tool | Shape | Notes |
|---|---|---|
| Orca (stablyai) | Electron desktop, MIT, ~15.7k★, YC | 30+ agents, SSH worktrees, mobile, Design Mode browser, GitHub/Linear |
| Emdash (generalaction) | Electron desktop, MIT, YC W26 | 25+ agents, SSH remote, Linear/Jira, tmux, local-first SQLite |
| Conductor / Nimbalyst / Superset | Mac apps / IDEs | kanban, diff review, in-app browser |
| Rmux / Herdr / Bosun / Repomon | Rust, terminal | multiplexers + orchestrators; Herdr exposes agent state over a Unix socket |
| container-use (Dagger) / Sculptor (Imbue) | Containers | per-agent containerized worktrees |
| Claude Code / Cursor 2.0 / Codex | Native | agent teams, parallel agents, worktree threads |
Two conclusions, and the second one matters more:
- "Fast, minimal, Rust, terminal-native" is not a wedge. Rmux, Herdr, Bosun and Repomon are all four of those already. Speed is table stakes in that camp, not differentiation.
- Not one of them — Electron or Rust, cockpit or multiplexer — provisions the environment.
No dependency install, no
.env, no port registry, no per-worktree database, no compose project. The gapV2.mdidentified is still open, in both camps.
Ranked by evidence strength, and graded honestly — some of this is well-supported, some is inference and is labelled as such.
| Pain | Evidence | Grade |
|---|---|---|
| Fresh worktree is inert (no deps/env), ports collide, DB shared | Independent write-ups + jacob's 9 issues + claude-squad #260 (8 reactions asking for exactly this) | Strong |
| Review/verification is now the ceiling, not codegen | "the bottleneck moves to review queues"; teams cap at 4–8 concurrent worktrees; the stated fix is previews — "click a link and see the feature running rather than reading the diff" | Strong |
| Laptop resource exhaustion at N agents | 5–7 agents comfortable, 2–4 GB RAM each, "memory, not CPU, is the concurrency bottleneck", advice to "stagger launches or limit concurrent builds" | Moderate — measured for agent processes; extending it to workz-managed dev servers/DBs is our inference |
| Monorepos are under-served | Nicolas Ha, first-party | Moderate — one report, needs detail |
| Want shareable env recipes | None found | Weak — do not build on this |
| Want a reproducible env lockfile | Indirect only ("passes tests locally but cannot reproduce the environment") | Weak |
Caveat on sourcing: the landscape research came from blogs, vendor comparison pages and aggregators — not raw Reddit/HN threads, some of which is SEO content. The strongest signal workz has is first-party (jacob, Nicolas, claude-squad #260). Prefer that. Validate before building anything graded Weak.
workz is the base system agent cockpits run on — not a sixth cockpit.
The Arch Linux analogy is the right identity and the wrong roadmap:
- Right: a minimal single binary you assemble yourself, composable primitives (CLI + hooks + MCP), no bundled GUI, zero-config defaults that are fully overridable, terminal-native, works under whatever cockpit you use. That is already what workz is. And Arch's real impact wasn't desktop share — it was being the base SteamOS shipped on. Orca/Emdash are the SteamOS here; workz is the base.
- Wrong as a plan: Arch's actual moats — the AUR and the Wiki — took two decades of community. "Be like Arch" does not tell you what to build. And the one Arch-derived feature we considered (a recipe registry) has zero observed demand.
So the identity drives how we build (small, composable, no GUI, hook-first). Evidence drives what we build.
The one Arch lesson worth stealing now: the Wiki. Docs are cheap, impossible to fake, and the thing other tools link to. Owning the definitive reference for "how to run N agents on one repo without collisions" would buy more credibility today than any feature.
- Hook-first. Everything works when invoked by another tool: non-interactive, idempotent, quiet, machine-readable.
- Zero-config by default, escape hatches for the 10%.
- Never lose user data. Merge, don't overwrite; managed content lives between markers.
- Small. One binary, minimal deps. If it needs tokio, it doesn't belong in workz.
- Boring reliability over surface area.
- NEW — evidence over narrative. Ship what a real user hit. An idea with no reporter behind it gets written down, not built. #16 exists because jacob asked; the recipe registry does not exist because nobody did.
workz allocates a port, a database and a compose project, then stops. It hands you a
configured-but-dead worktree. run closes that gap.
workz run [branch] # start the worktree's dev server on its allocated port
workz run --stop [branch] # stop it (reuses the reap path — kills the listener we own)
workz run --logs [branch] # tail its log
workz run --all # every worktree with an allocation
- Dev command from
[run] cmdin.workz.toml; auto-detected when unset (package.jsondevscript with the right package manager,cargo run,manage.py runserver, …). - Runs detached with the worktree's
.env.localin effect, soPORT/DATABASE_URL/COMPOSE_PROJECT_NAMEare already the isolated ones. - Logs to a per-worktree file under the state dir;
--logstails it. - Stop reuses
reap_branch— workz already knows exactly which ports it owns, so it never kills a process it didn't start.
The direct answer to the review bottleneck.
workz preview # table: branch · port · URL · status · what's listening
workz preview --json # machine-readable, for cockpits and agents
Built from primitives that already exist: the port registry plus listeners_on_port(). Liveness
is observed (is something actually listening on the range we allocated?), not tracked in a
state file that can go stale.
workz check [branch] runs the project's test/lint/build in the worktree and reports pass/fail,
machine-readable. Turns "did the agent's work actually work?" into one command an agent or a
cockpit can call.
workz is the only tool that knows every worktree's ports, DB and compose project, so it is the only one that can govern them: cap concurrently-running dev servers, suspend idle worktrees, reclaim resources. Real need at 4–8 agents — but confirm with jacob/Nicolas before building.
[[isolation.database]] blocks: several DBs per worktree (dev + test), each with a template and
its own managed env var. Already designed in the issue. Touches database dropping, so it gets
careful tests.
Nicolas Ha's report. Get specifics before designing: is it the symlinked-node_modules/pnpm
workspace problem (which [sync.overrides] node_modules = "copy" may already solve), per-package
ports ([isolation] services may already solve), or something genuinely missing?
The definitive guide to running N agents on one repo without collisions: per-host recipes, the isolation model, known-good strategy per stack, troubleshooting. Cheap, compounding, linkable.
Expose run, preview, check as MCP tools so agents can start their own environment and
verify their own work.
workz # status table
workz start <branch> # create worktree + sync (+ --isolated, --create-db, --carry-from)
workz sync [path] # idempotent env setup — the hook command
workz run [branch] # NEW — start the dev server on the allocated port
workz preview # NEW — which worktrees are live, with URLs
workz check [branch] # NEW (v0.16) — run tests/lint/build, machine-readable
workz switch [query] # fuzzy picker
workz list | status # unchanged
workz done [branch] # teardown (+ --cleanup-db)
workz clean [--merged] # prune
workz conflicts # cross-worktree overlap
workz env-diff # managed-block drift
workz reap [branch] # kill processes on allocated ports
workz doctor [--fix] # diagnostics
workz hook <host> # host integration recipes
workz claude-hook # Claude Code WorktreeCreate contract
workz init # setup wizard
workz mcp # MCP server
workz shell-init <shell> # shell integration
- A cockpit / GUI / desktop app. Orca and Emdash have the UI layer, funded, with a large head start. Being sixth there is worthless; being the layer they call is not.
- Rebuilding the TUI dashboard. v0.9 deleted it for good reasons. The only defensible view
is the environment/runtime dimension (
preview), which nobody else can render — and it stays a table, not a 4-panel app. - A recipe/config registry. Nice narrative, zero evidence. Parked until a user asks.
- Being an orchestrator. Still true from v2: workz sets tables; it doesn't seat guests.
- Containers as the default. The worktree+container hybrid is emerging as a standard, but
devcontainers-per-branch are widely reported as a workflow killer (slow rebuilds, re-auth).
Optional mode at most, and only after
run/previewland.
| Risk | Mitigation |
|---|---|
| A cockpit absorbs the environment layer natively | Depth is the defense: port registry + DB templates + compose + doctor + run/preview is a lot of surface to copy. And V2.md's answer still holds — if a host absorbs it all, the category was won by the idea. |
run becomes a bad process manager (zombies, stale PIDs) |
Don't track state we can observe: liveness comes from listeners_on_port, stop reuses the reap path that only touches ports workz allocated. |
| Scope creep back toward an ADE | §6 is the fence. Every new surface must be callable by another tool, not just by a human. |
| Building on weak evidence | §1.4 grades everything. Weak-graded ideas require a named reporter before they enter §4. |
Landscape research: 2026-07-27 session. Primary signal: issues #11–#28 (jacob-carlborg), claude-squad #260, and direct user feedback. Secondary: published comparisons of Orca, Emdash, Rmux, Herdr, Bosun, Repomon, container-use, Sculptor, Conductor, Nimbalyst, Superset.