{
  "markdown": "# Worktree Zero\n\n**Give every coding agent its own disposable workspace — for the disk cost of\nwhat it changes, with identities that never collide and cleanup that cannot\ndestroy work.**\n\nEach agent gets its own copy of your repository (a \"worktree\") in about a\nsecond, sharing files with your main checkout instead of copying them.\n\n### Install\n\n```bash\nbrew tap lonormaly/wt0\nbrew install wt0                   # macOS and Linux, prebuilt + checksummed\nnpm i -g worktree-zero             # installs the `wt0` command; or: npx worktree-zero doctor\n```\n\n### First command\n\n```bash\nwt0\n```\n\nRun with no arguments inside a Git repository, `wt0` reports what a\nworktree costs in this repository today, what changes with wt0, and exactly\nwhat to do next — the same report `wt0 doctor` prints (see \"First run\"\nbelow for a real example). `wt0 faq` answers common questions in plain\nlanguage.\n\nFrom there, `wt0` is one command between your agent fleet and Git:\n\n```bash\nwt0 run agent/fix-checkout -- codex exec \"fix the checkout bug\"\n```\n\nThat call creates a real linked worktree whose unchanged files are\ncopy-on-write clones — files that share disk space with one canonical copy\nof your checkout until one of them is edited — prepares dependencies from\nshared immutable stores, hands the runtime identities no other agent\ncollides with (a slot — a small per-worktree index; a machine-unique port\nwindow; a Compose project name), runs the command under a heartbeat lease\n(a claim on the worktree the agent renews every 30 seconds, so wt0 can tell\na live agent from an abandoned one), and leaves behind ownership evidence so\nthe whole runtime can be reclaimed safely later — even after a crash.\n\n> Status: design-partner phase with checksummed macOS, Linux, and\n> experimental Windows releases (ReFS/Dev Drive block-clone CoW, plain NTFS\n> fallback). FLAM and Builders Stack are the first measured design partners.\n\n## What a worktree costs you today — measured\n\nMost teams create a worktree with `git worktree add` and run their package\nmanager's install inside it — no shared store, no wt0. Nobody sees the\nrunning cost, because it is spread across dozens of checkouts nobody\nremembers to delete. Measured on an isolated APFS volume, physical\nfree-space deltas only, 3 worktrees per row unless noted:\n\n| Setup | Per extra worktree, today | Per extra worktree, wt0 | Ten worktrees, today → wt0 |\n| --- | ---: | ---: | ---: |\n| npm hoisted (Next app) | 388 MiB, 60–74 s | 4–5 MiB, 2–5 s | 3.8 GiB → 429 MiB |\n| Yarn classic (Next app) | 405 MiB, 7 s | ≈0–5 MiB, 3–4 s | 4.0 GiB → ≈430 MiB |\n| Bun hoisted, no store, cache on the same volume (Next app) | 4.5 MiB, 2 s | 2.7 MiB, 5 s | 45 MiB → 29 MiB |\n| Bun hoisted, no store, cache on the same volume (FLAM, 236k files) | 469 MiB, 67 s | 89 MiB marginal (179 MiB first worktree), 108 s | 4.58 GiB → 981 MiB |\n| Bun global store (FLAM) | 386 MiB, 8 s | 7.1 MiB, 7 s | 3.77 GiB → 71 MiB |\n| `git worktree add` alone (FLAM checkout) | 380 MiB, 3 s | 1.8 MiB, 2 s | 3.71 GiB → 18 MiB |\n\nwt0 shares the tracked checkout in every row — that is the constant win,\nand the last row is that win on its own. The fourth row (a 236k-file\nhoisted `node_modules`) was originally reported as no advantage for wt0,\non the reasoning that a per-file clone costs the same ~2 KB of metadata\nper file as Bun's own same-volume-cache materialization. That reasoning\nno longer holds and the number is settled, independently confirmed twice\n(a ten-worktree run and, separately, a six-worktree interleaved re-run,\nboth in flam-migration.md): wt0 clones the whole `node_modules` tree in\none `clonefile` call, at ~400 bytes of metadata per file, while Bun's own\ninstall still clonefiles package files out of its cache one at a time, at\n~2 KB per file — five times more per file for the identical tree. wt0\npays that whole-tree cost once per environment (179 MiB) and the cheaper\nmarginal cost (89 MiB) for every worktree after. Bun's `isolated` linker\nwith `globalStore = true` — one `bunfig.toml` line, the fifth row — still\nturns 236k files into 12k links and gives wt0 its largest margin, and\nremains the recommendation regardless. Fixtures, instrument, and every\nraw number:\n[flam-migration.md](docs/design-partners/flam-migration.md) (see \"The 2×2\"\nand \"Verification — hoisted node_modules per-worktree cost\"),\n[dependency-link-trees.md](docs/research/dependency-link-trees.md),\n[drift.md](docs/design-partners/drift.md).\n\n- Adding a package inside a worktree costs the package, not the tree — every\n  manager tested wrote 5–6 MiB for one added package, never the tree's full\n  size ([drift.md](docs/design-partners/drift.md)).\n- A seeded `.next/cache` survives an edit and rebuild 4× faster and 85%\n  smaller than a cold one — 622 ms/4.3 MiB versus 2.5 s/28.5 MiB\n  ([drift.md](docs/design-partners/drift.md)).\n- The first worktree of a base commit always pays a one-time baseline (wt0's\n  single shared, canonical copy of that commit's checkout, that every later\n  worktree clones from) — 517 MiB, measured on FLAM with a warm store —\n  before any later worktree of that commit clones for single-digit MiB\n  ([flam-migration.md](docs/design-partners/flam-migration.md)).\n\n## The problem\n\nAgent swarms multiply everything about a checkout except the history.\n\nGit worktrees share commits and blobs, but every worktree **materializes the\nfull working tree again**, and everything Git ignores is rebuilt from scratch:\n`node_modules`, `.next`, `.nx`, `dist`, local databases, emulators. Measured\non a real Next.js template (Builders Stack, same warm Bun global store on both\nsides):\n\n| Worktrees | Native Git + Bun physical | Worktree Zero + Bun physical | Reduction |\n| ---: | ---: | ---: | ---: |\n| 1 | 383.74 MiB | 391.38 MiB | -2.0% |\n| 2 | 767.17 MiB | 401.82 MiB | 47.6% |\n| 3 | 1,148.90 MiB | 411.35 MiB | 64.2% |\n| 4 | 1,532.74 MiB | 421.27 MiB | 72.5% |\n\nEach additional native worktree cost about 383 MiB. Each additional Worktree\nZero runtime cost about 10 MiB — a **97% reduction in marginal storage** —\nand the fourth worktree still passed the repository's real test suite.\n\nThat first-worktree row (-2.0%, essentially parity with native) predates\nderiving the baseline (the shared, canonical checkout described above) and\nthe first prepared environment (a sealed, shareable copy of installed\ndependencies) from the base checkout instead of a second physical copy of it\n([`flam-migration.md`](docs/design-partners/flam-migration.md#after---d13---the-first-worktree-2026-09-02)):\nmeasured on FLAM, the first worktree of a base commit now costs 15.7 MiB\nagainst a native 509 MiB.\n\nDuplication is only the first failure. Parallel agents **collide**: every dev\nserver wants port 3000, every Compose stack wants the project name, every\nbuild tool wants the same cache directory — and a shared writable `.next`\nbetween two live agents corrupts both. And when agents finish or crash, they\n**leak**: our first design partner's repository had 40 registered worktrees,\nmulti-gigabyte stale dependency layouts, 7.7 GiB of Next output, 1.4 GiB of\nWrangler state, and a 1.2 GiB Nx daemon log — with no way to tell what was\nsafe to delete.\n\nThree problems, one lifecycle: **duplication, collision, abandonment.**\nWorktree Zero exists because no worktree tool owned all three.\n\n## How wt0 solves it\n\n### 1. Storage: classify, then share\n\nOne mechanism cannot serve tracked files, dependencies, and build output.\nWorktree Zero classifies the data before deciding:\n\n| Data | Example | Rule |\n| --- | --- | --- |\n| Tracked working files | `src/`, images, fixtures | CoW-clone every unchanged file from one canonical baseline (APFS clonefile, Linux reflink, Windows ReFS block clone) |\n| Installed dependencies | `node_modules` | Reuse the package manager's native store first; attach a private CoW view of the verified post-install environment for what remains |\n| Generated state | `.next`, `.nx`, `dist`, Wrangler data | Keep immutable keyed caches shared, move mutable state into owned per-runtime storage, retire it at teardown |\n\nPackage managers are adapters, not prerequisites: Bun, pnpm, npm, and Yarn\nare detected from the lockfile, their native sharing is preserved, and\nprepared environments are keyed by lockfile, manifests, manager version, OS,\nand ABI — changing one dependency starts from the nearest compatible snapshot\ninstead of a full copy. No virtual store is *required*: without one, wt0\nseals the manager's own install once and clones it per worktree. The\nmanager's store is still recommended — it is the smallest footprint, and it\nshares across repositories, which a per-repository seal cannot. A checked-in\n`.wt0-seed` additionally clones the base checkout's build caches\n(`.nx/cache`, `.next/cache`) — and its `node_modules`, when the lockfile is\nidentical and no cheaper native store (pnpm, Bun's global store, Yarn's\n`nodeLinker: pnpm`) is already active for it — into every new worktree, so\nthe first build starts warm and a plain `npm install` finds nothing to do\n(measured: three paths touched, 0 MiB written). `wt0 run` applies the same\nownership rule to Cargo\ntarget directories, Nx workspace state, and Wrangler local persistence.\n\n### 2. Identity: collision-free by construction\n\nEvery runtime receives, with zero project logic:\n\n- a **slot** (smallest free index, `WT0_SLOT`);\n- a **hundred-port window** (`WT0_PORT_BASE`) claimed from a machine-global\n  registry — unique across every repository on the machine, bind-probed\n  against foreign listeners, released on removal;\n- a default **`COMPOSE_PROJECT_NAME`** so Docker Compose stacks isolate per\n  worktree;\n- a **runtime id** (UUIDv7) that keys namespaces, labels, and receipts.\n\nThe [Tilt extension](integrations/tilt/README.md) maps the same identities\ninto per-runtime Tilt namespaces, offset port forwards, and one-shot\n`tilt ci` test environments; [docs/dev-environments.md](docs/dev-environments.md)\ndefines the environment tiers, including shared-services setups where HMR\nlives.\n\n### 3. Lifecycle: cleanup that cannot destroy work\n\nEvery runtime carries an ownership marker and a lease; `wt0 run` heartbeats\nit every 30 seconds. Garbage collection is **refusal-first**: `wt0 gc` is a\ndry run by default, `--force` does not exist, and `wt0 gc --apply` removes a\nworktree only when *all* of these hold:\n\n- Worktree Zero owns it, on a preserved branch (never a detached commit);\n- its lease is old enough, and Git reports no modified or untracked work;\n- no process has a working directory or open path inside it; and\n- every ignored path is recognized generated state, or explicitly reviewed\n  via a checked-in `.wt0-generated` policy (sensitive paths like `.env*` can\n  never be allowed).\n\nAnything else is preserved and reported. Crashed agents leave leases that\nexpire and receipts that `wt0 prune` reconciles — never orphans without\nevidence. Checked-in lifecycle hooks (`.wt0/hooks/post-create`,\n`pre-remove`) boot and tear down project environments; a failing hook rolls\nback the create or vetoes the removal, and can never be bypassed into a\ndeletion. The full contract — lease mechanics, every GC guard, the\n`.wt0-generated` review policy, and the hook API — is in\n[docs/lifecycle.md](docs/lifecycle.md).\n\n## What wt0 is, and is not\n\nThe required surface is four commands — `create`, `run`, `remove`, `gc` —\nplus one reviewed policy file (`.wt0-generated`). Everything else is\noptional and additive: lifecycle hooks, `fleet` and `events`, the MCP\nserver, shared stores, port windows, owner metadata, seeding. `wt0 doctor`\nanswers the only question that matters in one screen: whether the promise\nholds on this machine — copy-on-write available, dependencies shared, and\ngenerated state bounded — and names each shortfall.\n\nThree things wt0 deliberately does not do:\n\n- **It does not replace Git or your package manager.** Git owns refs and\n  history; the manager owns resolution and its own store. wt0 shares what\n  they leave duplicated and cleans up what they leave behind.\n- **It does not deduplicate active build output.** `.next`, `.nx`, and\n  emulator state are mutable per worktree by nature; wt0 bounds them (owned\n  storage, retired with the runtime), reclaims them safely (policy + `gc`),\n  and can warm caches from the base checkout — it never shares a writable\n  build directory between two live agents.\n- **It does not require a virtual store.** Without one, wt0 seals the\n  manager's own install once and clones it per worktree. The manager's\n  store is recommended because it is smaller and shares across\n  repositories.\n\n## Built for agents\n\nAgents call one versioned, non-interactive contract — JSON CLI, MCP server,\nand portable skill are the same implementation:\n\n- **Discovery**: `wt0 capabilities --json` names the CoW backend, detected\n  package managers, generated-state tools, store levels, and hooks before\n  anything is created. Planned adapters report as planned, never as a silent\n  success.\n- **Idempotency**: `wt0 create`/`run` accept `--idempotency-key`; a retried\n  request returns the existing runtime (`\"reused\": true`) instead of failing\n  or double-creating. A different key is refused, never handed someone\n  else's runtime.\n- **The fleet map**: `wt0 fleet --json` returns every runtime with branch,\n  owner, slot, port window, idle time, mode, and owned storage — cheap by\n  default (no `git`, no `lsof`, no tree walk), filterable (`--idle`,\n  `--owner`, `--prefix`, `--unmanaged`, …) and sortable (`--sort\n  idle|branch|size`). Merged/dirty/live status and size are opt-in\n  (`--merged`/`--dirty`/`--live`/`--size`, or `--facts` for all four) since\n  each spawns a process or walks a tree — the one call an orchestrator\n  needs to reason about the swarm without paying for facts it won't use.\n  `wt0 events --follow` streams the append-only lifecycle log (created,\n  reused, removed, reaped, adopted).\n- **Concurrency is tested, not assumed**: CI drives 24 simultaneous\n  creates and removes against one repository on Linux, macOS, and Windows —\n  and runs the same suite on ReFS and loopback Btrfs volumes so the CoW\n  paths are exercised — asserting disjoint slots, disjoint port windows,\n  single-owner contended creates, and a corruption-free registry.\n\n### Install for an agent\n\n```bash\n# Portable skill (any host that discovers .agents/skills)\nnpx skills add lonormaly/worktree-zero --skill worktree-zero\n\n# Claude Code\nclaude plugin marketplace add lonormaly/worktree-zero\nclaude plugin install worktree-zero@worktree-zero\n\n# Codex\ncodex plugin marketplace add lonormaly/worktree-zero --ref main\ncodex plugin add worktree-zero@worktree-zero\n\n# Gemini CLI (extension bundling the MCP server)\ngemini extensions install https://github.com/lonormaly/worktree-zero\n```\n\n`wt0 mcp serve` speaks MCP over stdio (spec 2026-07-28, negotiating down to\n2024-11-05), so Cursor, GitHub Copilot, OpenCode, Grok, NanoClaw, OpenClaw,\nHermes, Slack agents, and any other MCP client call the same lifecycle — see\n[vendor integrations](docs/vendor-integrations.md) for each host's exact\nconfiguration. Wrappers may translate transport, but must not reimplement\ncleanup or weaken a refusal.\n\n### First run\n\nRunning `wt0` with no arguments (or `wt0 doctor`) answers whether the\npromise holds here in plain language a newcomer — human or agent — can act\non without reading any of this document: what a worktree costs in this\nrepository today, what changes with wt0, and exactly what to do next. A\nreal run against a design partner's repository, example:\n\n```text\nwt0 — Worktree Zero · cheap, isolated Git worktrees for coding agents\n\n  Each agent gets its own copy of your repository (a \"worktree\") in about a second, sharing\n  files with your main checkout instead of copying them. Below: what a worktree costs in this\n  repository today, what changes with wt0, and what to do next.\n\n📦 This repository  /path/to/your-repo\n   1.6 MiB of tracked files (316 files) · Bun with a plain node_modules folder (70,124 files)\n   Nx · Tilt · Portless · docker-compose\n   Filesystem: APFS — copy-on-write available ✅ (worktrees share files at no extra disk cost)\n\n💾 What one agent's worktree costs\n                                       today (git worktree add + bun install)   with wt0   saving\n   one worktree, ready to work          ≈ 139 MiB                     ≈ 27 MiB    5.2× · −81%\n   ten agents                           ≈ 1.4 GiB                     ≈ 0.3 GiB   4.7× · −79%\n   with Bun's shared package store on (step 1 below)      ≈ 7 MiB each 20× · −95%\n   Estimates: this repository's file counts × per-file costs measured on a 236,000-file\n   monorepo. `wt0 faq costs` explains.\n\n⚡ Speed   a worktree is ready in ≈ 1–2 s, and `git status` inside it is instant.\n🔌 Ports   each worktree gets its own 100-port range and a short name, so agents never collide.\n\n🎛️ Dev environment\n   Tilt — 9 ports, 8 names hard-coded; two agents running it at once will collide.\n      → wt0 init tilt — Tiltfile snippet deriving TILT_PORT from WT0_PORT_BASE\n   docker-compose — 2 ports hard-coded; two agents running it at once will collide.\n      → wt0 init compose — compose.wt0.yaml sets COMPOSE_PROJECT_NAME=${WT0_SLUG:-local}\n        and derives host ports from WT0_PORT_BASE\n🧹 Build output   982 MiB of ignored build files (.nx, dist, …). wt0 never deletes files it has\n                  not been told are disposable, so a short list of those folders is needed\n                  before `wt0 gc` can reclaim this space.\n\n🚀 What to do next\n   1. Turn on Bun's shared package store — packages live in one place and every worktree links to\n      them. Add to bunfig.toml:\n          [install]\n          linker = \"isolated\"\n          globalStore = true        (needs Bun 1.3.14 or newer)\n      → node_modules per worktree: 27 MiB → 7 MiB, and installs get faster.\n   2. Tell wt0 which build folders are disposable (things like .nx, .next, dist — safe to delete\n      once a worktree is done). Run: wt0 init generated --apply, then review the\n      .wt0-generated file it writes.\n      → `wt0 gc` can then reclaim 982 MiB from abandoned worktrees.\n   3. Give this repository's Tilt setup its own ports and hostnames per worktree, so two agents\n      running Tilt at the same time don't collide. Run: wt0 init tilt (dry run; add --apply\n      to write it).\n      → every worktree's Tilt UI, ports, and *.localhost routes become collision-free.\n   4. Give this repository's docker-compose setup its own project name and ports per worktree.\n      Run: wt0 init compose (dry run; add --apply to write compose.wt0.yaml).\n      → COMPOSE_PROJECT_NAME=${WT0_SLUG:-local} and host ports derived from WT0_PORT_BASE.\n   5. Start every worktree with a warm build cache instead of a cold one. Run: wt0 init seed --apply\n      → copies .nx/cache from your main checkout into each new worktree, free (copy-on-write).\n\n   Then:  wt0 create <branch> --owner <you-or-agent-id>   ·   wt0 fleet   ·   wt0 remove <path>\n   More:  wt0 faq   ·   https://github.com/lonormaly/worktree-zero#faq\n```\n\n`wt0 init` writes the setup `doctor` just recommended, instead of you (or an\nagent) copying it by hand — a dry run by default, `--apply` to write, and it\nnever overwrites an existing file without `--force`:\n\n```bash\nwt0 init                    # doctor's steps, and which init target closes each\nwt0 init generated --apply  # writes .wt0-generated from this repo's own ignored build output\nwt0 init seed --apply       # writes .wt0-seed from detected caches (Nx, Turbo, Next, node_modules)\nwt0 init tilt --apply       # writes tilt_up.sh / tilt_down.sh, lifecycle hooks, and a Tiltfile snippet\nwt0 init compose --apply    # writes compose.wt0.yaml, deriving project name and host ports from wt0\nwt0 init dev --apply        # writes a generic post-create hook for any dev server (not just Tilt)\nwt0 create agent/first-task # now create the first thin runtime\nwt0 fleet --idle 7d         # what's been sitting idle a week or more\nwt0 gc --merged --idle 7d   # reap what's idle that long AND already merged (dry run first)\n```\n\n### Dev environments: Tilt, docker-compose, or plain dev servers\n\nNot everyone uses Tilt. Whatever starts a project's dev stack — Tilt,\n`docker compose`, a devcontainer, a Procfile-style process manager\n(overmind, foreman, mprocs, `concurrently`), Skaffold/Garden/DevSpace, or a\nplain `next dev`/`vite`/`wrangler dev` script — the fix is the same in\nspirit: read the port and project name from `wt0`'s per-runtime identity\n(`WT0_PORT_BASE`, a disjoint hundred-port window; `WT0_SLUG`, a label-safe\nbranch name) instead of hard-coding them, so two agents' worktrees never\nfight over the same port, hostname, or container. `wt0 doctor`'s\n\"🎛️ Dev environment\" block names every tool it detects, the literal\nports/hostnames each one hard-codes, and the concrete fix for that tool.\nTwo design partners already run the Tilt pattern in production: FLAM's\n`.wt0/hooks/post-create` pins every listener inside its runtime's own port\nwindow (`TILT_PORT=\"$WT0_PORT_BASE\"`, `DB_PORT=\"$((WT0_PORT_BASE + 1))\"`,\n…), and Builders Stack's `tilt_up.sh` / `.devops/Tiltfile` derive the Tilt\nUI port from `WT0_PORT_BASE` and suffix every\n[Portless](https://github.com/vercel-labs/portless) route with\n`-${WT0_SLUG}`. `wt0 init tilt` writes exactly that pattern — boot/stop\nscripts, lifecycle hooks, and a Tiltfile snippet — for a project that\ndoesn't have it yet; see the [Tilt integration](integrations/tilt/README.md)\nfor the full extension API (`wt0_port`, `wt0_namespace`,\n`wt0_shared_namespace`, …) and the shared-services tier for stacks too heavy\nto boot fresh per worktree. For docker-compose, `wt0 init compose` proposes\na `compose.wt0.yaml` override mapping each literal host port to a\n`WT0_<SERVICE>_PORT` variable (documented, computed from `WT0_PORT_BASE` in\na post-create hook — compose interpolates `${VAR:-default}` but can't do\narithmetic itself); `COMPOSE_PROJECT_NAME` is already set per worktree by\n`wt0 run`. For everything else, `wt0 init dev` writes a generic\n`.wt0/hooks/post-create` that exports `PORT=$WT0_PORT_BASE` and a\n`.env.wt0` any dev script can source.\n\n## Honest measurement\n\n“Zero” is a measured direction, not a claim that bytes do not exist. Every\nclone still reports its full logical size — Finder and `du` count shared\nblocks once per file, so eight cloned source trees can *display* 605 MB while\nthe volume allocates 68 MB. Worktree Zero receipts therefore separate logical\nsize from physical allocation and use the filesystem free-space delta as the\nnumber that proves a saving:\n\n```text\nlogical files visible:          390 MB\nphysical allocation at create:  3.23 MB\nshared source baseline:         yes\nmeasurement:                    filesystem free-space delta\n```\n\nExisting fleets migrate too: `wt0 migrate --all --apply` converts native\nworktrees in place (identical clean files become clones; changed, dirty, or\nambiguous files stay private), then proves every checkout is still Git-clean:\n\n| Filesystem | Physical before | Physical after | Space returned |\n| --- | ---: | ---: | ---: |\n| macOS APFS | 389.21 MiB | 187.68 MiB | 201.53 MiB |\n| Linux Btrfs | 407.12 MiB | 200.77 MiB | 206.34 MiB |\n\n### When you do not need it\n\nOne or two short-lived worktrees in a small source-only repository gain\nlittle: Git plus a sharing package manager is often sufficient. Worktree Zero\nearns its place when several agents run in parallel, when tracked assets are\nlarge, when installed trees repeat per worktree, or when abandoned runtimes\nhave become nobody's job to clean.\n\n## Why Git alone repeats the files\n\nA branch is a name for a commit; the commit maps paths to blobs stored once\nin the object database. Checking out a branch *materializes* that map as\nordinary files — and Git materializes it fully in every linked worktree,\nbecause blobs are compressed and packed, so checkout reconstructs bytes\nrather than cloning blocks. Ten worktrees of a 300 MiB tree cost about 3.3\nGiB of working files under native Git.\n\nWorktree Zero creates the missing canonical checkout: one immutable baseline\nper commit (shared across branches, relocatable and layerable via\n`WT0_STORE` — see the [cloud RFC](docs/cloud-architecture.md)), cloned\nfile-by-file with copy-on-write. Every worktree still holds complete,\nindependently editable files with private inodes; unchanged files simply\nshare physical blocks until edited. Where the filesystem cannot clone\n(ext4, NTFS), the receipt says so explicitly — a fallback is reported, never\nsilently absorbed, and `--require-cow` makes it a refusal.\n\n## The Zero contract\n\n| Goal | Contract |\n| --- | --- |\n| Near-zero extra tracked-file blocks | Use copy-on-write/reflink when measured; report an explicit fallback. |\n| Near-zero repeated dependency blocks | Reuse the package manager's store, then provide private CoW views of verified post-install closures. |\n| Zero unsafe shared state | Share immutable answers; isolate mutable databases, emulators, and workspace metadata. |\n| Zero collisions | Give every runtime stable identities for every process and resource. |\n| Zero cleanup debt | One lifecycle owns create, run, stop, remove, expiry, and crash reconciliation. |\n| Zero performance folklore | Publish physical allocation, startup, cache, teardown, and failure receipts. |\n\n## Release gate\n\nWorktree Zero is not stable until a new agent integration can:\n\n1. install one CLI and portable skill without editing project source;\n2. discover capabilities with one non-interactive call;\n3. create and run a usable runtime with one non-interactive call;\n4. consume the same versioned result through JSON or MCP;\n5. retry safely after a timeout without creating a second runtime;\n6. clean up without learning project-specific paths; and\n7. receive a structured human request when cleanup is unsafe.\n\n## Going deeper\n\n- [Autonomous-agent protocol](docs/autonomous-agents.md) — exit codes,\n  receipts, refusal semantics.\n- [Runtime lifecycle](docs/lifecycle.md) — leases, every GC guard, the\n  generated-state review policy, and the hook API.\n- [Prepared environments](docs/prepared-environments.md) — the\n  dependency-sharing contract and per-manager proofs.\n- [Dev environments](docs/dev-environments.md) — environment tiers, HMR,\n  and per-worktree test stacks.\n- [Cloud architecture RFC](docs/cloud-architecture.md) and\n  [k3s reference deployment](deploy/k3s/README.md) — shared stores for\n  Kubernetes sandboxes.\n- [Compatibility contract](docs/compatibility.md) and\n  [FLAM design-partner brief](docs/design-partners/flam.md).\n\n## FAQ\n\nThe full FAQ — every question below plus the ones newcomers ask most\n(\"What is a worktree?\", \"What does 'shared package store' mean?\", \"What\ndoes wt0 delete, and when?\", \"Do I need Tilt/Bun/a shared store at all?\",\nand more) — lives in [`docs/faq.md`](docs/faq.md), the same text\n`wt0 faq` prints (`wt0 faq costs`, `wt0 faq ports`, `wt0 faq safety`,\n`wt0 faq tilt` filter it by topic). The short version:\n\n- **`npx wt0` says 404.** The npm package is `worktree-zero` — the registry\n  refuses the bare name `wt0` as too similar to existing short packages —\n  but the installed command is still `wt0`. Use `npx worktree-zero …` or\n  `npm i -g worktree-zero`.\n- **Where does a worktree live?** Under\n  `<parent>/<repo-name>-worktrees/<slug>/` by default — a sibling directory\n  next to your checkout, same volume (copy-on-write still applies) but\n  outside the repository's own tree, so no bundler or watcher's stock\n  \"ignore .git\" rule hides it. Override with `--path`, `WT0_WORKTREES_DIR`,\n  or a `worktrees_dir` line in a checked-in `.wt0/config`.\n- **What does a worktree cost?** The checkout is a copy-on-write clone — a\n  few MiB regardless of checkout size (see the table above and `wt0 doctor`\n  for this repository's own numbers). Installed dependencies cost what your\n  package manager's layout costs — see `wt0 faq costs` for the full\n  breakdown.\n- **Will it delete my work?** No — `gc` and `remove` refuse dirty trees,\n  unmerged branches, worktrees they don't own, and any ignored file they\n  don't recognize as safe build output; a live process blocks removal\n  outright. See `wt0 faq safety` for exactly what's refused and what's\n  reclaimed.\n- **What happens when an agent crashes?** Its lease (a claim it renews every\n  30 seconds) goes stale; `wt0 gc --idle` reaps the worktree and frees\n  its port range, and `wt0 prune` recovers a worktree that vanished outside\n  wt0 entirely (`rm -rf`, a wiped volume) as a tracked orphan.\n- **How do I clean up old worktrees?** `wt0 fleet --idle 7d` shows what's\n  idle, merged, dirty, and live so you know what's safe to drop; `wt0 gc\n  --merged --idle 0s` reaps everything already merged and forgotten,\n  regardless of age; `wt0 remove --merged` does the same removal\n  immediately. See `wt0 faq cleanup` for every selector.\n- **Is `doctor`'s \"what to do next\" list a blocker?** No — `wt0 create`\n  works regardless. Its exit code reflects only whether dependencies are\n  shared and build output is within a safe size budget; the list is a\n  broader wish-list on top of that.\n- **Windows?** ReFS/Dev Drive gives copy-on-write, and the storage numbers\n  hold (9.8 MiB per worktree in CI). `wt0 create` is slower there today\n  (files are cloned one at a time). Plain NTFS falls back to an ordinary\n  checkout and says so.\n- **What is simgit?** The copy-on-write engine wt0 started from, included\n  under its MIT license with history; wt0 adds everything around it (see\n  [Origins](#origins) below).\n\n## Origins\n\nThe source engine began in [simgit](https://github.com/abendrothj/simgit) by\nJake Abendroth and is included under the MIT license with its Git history and\ncopyright preserved. Worktree Zero adds the full runtime lifecycle around it\nand publishes only the `wt0` interface.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 29807,
  "sha": "0241f758483c3a1662d87b07cdd533562d290c580abdb149e1a40e4d65668d3f",
  "repo_slug": "lonormaly/worktree-zero",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_lonormaly_worktree_zero_81a97174/readme"
}