{"slug": "show-hn-100ms-copy-on-write-workspaces-for-ai-agents-on-macos", "title": "Show HN: 100ms copy-on-write workspaces for AI agents on macOS", "summary": "Developer Gabriel V. Fonseca released Replica, an open-source macOS CLI that creates a fully installed copy of a project for each AI agent run in about 100 ms at N = 1 and about 230 ms at N = 10 concurrent workspaces, versus seconds for git clone plus an install. Replica builds a base git clone with dependencies installed once, then clones it with a single clonefile(2) APFS copy-on-write call so data blocks stay shared until a file changes; each workspace is a real git checkout that can branch, commit and push while the base stays untouched. Disk use is bounded by TTL expiry, least-recently-used eviction, a byte cap and an optional quota-limited APFS volume, and the tool ships with --json output, documented exit codes and skills for Claude Code, Cursor, Copilot, Zed and Aider; it requires macOS on an APFS volume with the base and workspaces on the same volume, with binaries for Apple Silicon and Intel.", "body_md": "**Replica gives every agent run its own fully installed copy of your project, created in milliseconds with APFS copy-on-write. Each copy is a real git checkout, and automatic cleanup keeps total disk use bounded.**\n\n```\ncd \"$(replica new --ttl 2h --name fix-login)\"   # a ready workspace; the path goes to stdout\ngit checkout -b agent/fix-login && git commit -am \"fix login\" && git push -u origin agent/fix-login\nreplica rm <id>                                 # done; or let the TTL expire\n```\n\nAgent workloads are dominated by creating and deleting small files (a checkout,\n`node_modules`, build output), and that's where macOS is slowest. A fresh\ninstall takes seconds to minutes before the agent does any work.\n\nReplica builds a **base** once: a git clone with its dependencies installed.\nEach `replica new` clones that base with one `clonefile(2)` call. The data\nblocks stay shared with the base until a file changes, so the new workspace is\nready almost at once. Measured on an Apple M1 Max, `replica new` of a 1,700-file\nproject takes about 100 ms at N = 1 and about 230 ms at N = 10 concurrent\nworkspaces, versus seconds for `git clone` plus an install.\n[Numbers and methodology](https://github.com/gabrielvfonseca/replica/blob/main/docs/BENCHMARKS.md).\n\n- **Fast workspaces.** A clone of a 1,700-file project takes about 100 ms at N = 1 (about 230 ms with 10 concurrent workspaces), against seconds for`git clone` plus an install. Exact numbers vary with machine load; see[docs/BENCHMARKS.md](https://github.com/gabrielvfonseca/replica/blob/main/docs/BENCHMARKS.md) for the full table and methodology.\n- **Real git.** Each workspace is a full git checkout. It can branch, commit, and push, and the base stays untouched.[Details below](#git-branch-commit-and-push-from-a-workspace) .\n- **Bounded disk.** TTL expiry, least-recently-used eviction, a byte cap, and an optional dedicated APFS volume with a quota.\n- **Cheap updates.**`replica base refresh` brings the base up to date with its remote without a full rebuild.[Details below](#keeping-the-base-fresh) .\n- **Agent-ready.** A stable CLI with`--json` output, documented exit codes, and skills for Claude Code, Cursor, Copilot, Zed and Aider.\n- **Concurrency tested.**`tests/concurrency.rs` runs 10 simultaneous`replica new` /use/`rm` cycles with zero SQLite busy errors, no corruption, and all workspaces created and removed.`replica gc` skips workspaces with a fresh lease (`.replica/lease` ), so a launchd gc every 10 minutes never deletes a workspace an agent is using.\n\n- macOS on an APFS volume. Replica uses `clonefile(2)` , which Linux does not provide. Tested on macOS 26.6 (Apple M1 Max).\n- The base tree and every workspace must be on the **same APFS volume** . Clones cannot cross volumes, and Replica refuses rather than silently copying.\n\nBinaries are published for macOS on Apple Silicon (`arm64`) and Intel (` x86_64`). A universal binary covers both.\n\n```\n# Homebrew is not available yet; see HOMEBREW.md.\n\n# Installer script: verifies the download against sha256sums.txt\ncurl -fsSL https://raw.githubusercontent.com/gabrielvfonseca/replica/main/scripts/get-replica.sh | sh\n\n# From source (needs a Rust toolchain, https://rustup.rs)\ngit clone https://github.com/gabrielvfonseca/replica.git && cd replica\nmake release && PREFIX=$HOME/.local make install\n```\n\nRun `replica help` for a guided overview, or `replica help quickstart` to get started.\n\n**1. Choose a volume.** A dedicated APFS volume with a quota is the safest setup, because clones can never fill your main disk.\n\n```\ndiskutil apfs list                                   # find your APFS container\n./scripts/setup-volume.sh disk3 100g Work            # creates /Volumes/Work, turns off Spotlight indexing there\nexport REPLICA_ROOT=/Volumes/Work/replica\n```\n\nAny APFS directory works too. Add `REPLICA_MAX_BYTES` to cap its size. See [DISK_SAFETY](https://github.com/gabrielvfonseca/replica/blob/main/docs/DISK_SAFETY.md) for the trade-offs.\n\n**2. Build a base once.**\n\n```\nreplica base build --repo https://github.com/you/proj.git --setup \"npm ci\"\nreplica base check                                   # find build output that breaks when cloned\n```\n\n**3. Create, use, and remove workspaces.**\n\n```\ncd \"$(replica new --ttl 4h --name feature-x)\"        # path on stdout, status on stderr\neval \"$(replica env <id>)\"                           # per-workspace TMPDIR and shared caches\nreplica touch <id>                                   # keep a long session out of LRU eviction\nreplica list                                         # table; add --json for scripts\nreplica rm <id>                                      # remove one (idempotent)\n```\n\n**Branches with different lockfiles.** If you create a workspace from a branch\nwhose lockfile differs from the base, use `--ref`:\n\n```\nreplica new --ref my-feature-branch\n```\n\nReplica compares the branch's lockfile hash with the base's recorded hash. If\nthey match, the workspace is cloned directly (`cloned directly`). If they differ,\nReplica clones the base, checks out `my-feature-branch`, then runs the setup\ncommand (an incremental install) so the workspace gets correct dependencies, and\nreports `lockfile drift on branch my-feature-branch; running incremental install`.\nThe CLI always tells you which path it took.\n\n**4. Give your agents the skill.**\n\n```\nnpx skills add gabrielvfonseca/replica               # skills.sh CLI: all six skills\nreplica setup --dry-run                              # see what setup would write for Claude Code, Cursor, Copilot, Zed, Aider\nreplica setup                                        # write it\n```\n\nYes. A workspace is a complete git repository, not a read-only copy:\n\n| Operation | In a workspace | Effect on the base | \n|---|---|---|\n| `git checkout -b` ,`git commit` | Works. Commits live in the workspace's `.git` | None | \n| `git push origin <branch>` | Works, to the remote the base was built from | None | \n| `git pull` ,`git fetch` | Works | None | \n| `git status` ,`git diff` | Works | None | \n\nThings to know:\n\n- **Remote credentials.**`push` uses whatever credentials git uses on this machine (SSH keys, a credential helper). Replica does not add or store any.\n- **The remote is the one you built from.**`origin` in a workspace is the`--repo` you passed to`base build` . If that is a local path, pushes go to that path.\n- **Workspaces are independent.** Two workspaces on the same branch will conflict on push, the same as two clones would. Use one branch per workspace.\n- **Verified.**`tests/git_workspace.rs` builds a base from a bare repo, commits and pushes from a workspace, and checks that the origin and the base are as expected.\n\nFor agents that open pull requests, the flow is: `replica new`, work and commit on a branch, push, open the PR with `gh pr create`, then `replica rm`.\n\nWhen the remote moves on, `replica base refresh` updates the base. It does not rebuild from scratch:\n\n1. Clonefiles the current base. This copies metadata only, so it is quick and uses almost no extra disk.\n2. Runs `git fetch` and resets the copy to`origin/HEAD` . Only files that changed upstream are rewritten.\n3. Re-runs setup **only if a lockfile changed** . If none did, setup is skipped entirely.\n4. Swaps the new base in. Existing workspaces are unaffected, because each one owns its blocks.\n\nSo an upstream commit that does not touch dependencies costs a fetch and a checkout. A lockfile change costs about as much as the setup command itself. If the fast path fails for any reason, refresh falls back to a full rebuild.\n\nCheck freshness with `replica base status`, and use `replica new --require-fresh` to refuse a stale base.\n\n- **At creation** , a workspace adds APFS metadata for every file and directory it contains. For the benchmark fixture (about 1,700 files) that is about 1.4 MB. Data blocks are shared with the base.\n- **After the agent works** , every file it changes takes real space, because APFS copies the blocks that change. Rewriting 500 MB of build output costs 500 MB, and so does a`npm rebuild` that rewrites`node_modules` .\n- **Deleting** a workspace frees only the blocks no other file shares. A fresh workspace frees little, and a heavily changed one frees much more.\n\nThis is why the TTL, LRU eviction, and byte cap exist. [DISK_SAFETY](https://github.com/gabrielvfonseca/replica/blob/main/docs/DISK_SAFETY.md) explains each one.\n\nSpotlight can also add writes on a busy volume. `scripts/setup-volume.sh` turns indexing off for the dedicated volume only (it needs `sudo`). We have not yet measured how much that changes benchmark results.\n\n- **Path-dependent build output.** Some tools write absolute paths into their output: Python venvs,`node_modules/.bin` scripts, TypeScript`.tsbuildinfo` . These break in a clone. Run`replica base check` to find them, then fix them with`--post-clone` or by regenerating them. See the[replica-base skill](https://github.com/gabrielvfonseca/replica/blob/main/skills/replica-base/SKILL.md) .\n- **Cargo `target/` clones safely but adds cost.** A cloned`target/` gives a correct incremental no-op build (~20 ms, no recompile) when nothing changed, and recompiles only changed crates after a source touch — it does not force a full rebuild. However,`target/` is created by the setup command, so`.gitignore` does not keep it out of the base. Exclude it another way: either don't build`target/` during setup, or add an exclusion option to your base build. A cloned`target/` of a large project can add tens of MB of APFS metadata per clone, so exclude it if disk cost matters. A shared`CARGO_TARGET_DIR` under`$REPLICA_ROOT/cache` keeps incremental builds fast but reintroduces Cargo's file-lock waiting, so parallel agents can block on`Blocking waiting for file lock` . For parallel use, consider`sccache` instead of a shared target dir.\n- **Cost scales with file count.** Each clone writes metadata for every file. Replica is much faster than copying or cloning file by file, but it is not free, and very large trees (hundreds of thousands of files) have not been measured.\n- **Same volume only.** Source, base, and workspaces must share one APFS volume.\n- **Not a speedup inside a running agent.** Replica makes workspace creation fast. It does not speed up reads or writes during a run, does not reduce the RAM or CPU used by running many agents at once, and does not fix Spotlight or XProtect scanning.\n- **macOS only.** Linux and Windows are out of scope.\n\nThe suite in [`benchmarks/`](https://github.com/gabrielvfonseca/replica/blob/main/benchmarks/README.md) compares `replica new` with\n`git clone` plus install, `git worktree` plus install, `pnpm` with the global\nvirtual store, and `cp -c`, and it also measures `replica rm` and\n`replica base refresh`, at concurrency N = 1, 5, and 10.\n\n```\nmake release                                         # target/release/replica\nmake bench                                           # bundled fixture (~15 min)\nmake bench CONCURRENCY=1,5,10                        # parallel workspace creation\n```\n\nFull results, methodology, machine details, and exact commands are in\n[docs/BENCHMARKS.md](https://github.com/gabrielvfonseca/replica/blob/main/docs/BENCHMARKS.md).\n\nHeadline (Apple M1 Max, macOS 26.6.2, under load, 1,739-file npm project):\n\n| Concurrency | `replica new` median | `cp -c -R` median | `git clone` + setup median | \n|---|---|---|---|\n| N = 1 | ~100 ms | ~958 ms | ~3.96 s | \n| N = 10 (all at once) | ~230 ms | ~3.55 s | ~4 s | \n\n`replica new` is about 15x faster than `cp -c -R` even with 10 concurrent\nworkspaces, and tens of times faster than `git clone` plus an install. The\none-time `replica base build` (~2–3 s) is less than a single `git clone` +\nsetup, so Replica comes out ahead on the very first workspace.\n\n- **2026-11-09, under load** (1-minute load 171–184 on 10 cores). These\nabsolute times are inflated by the shared machine load; relative ordering\nheld, but do not quote the ratios as settled. Exact numbers and P95 values\nare in[docs/BENCHMARKS.md](https://github.com/gabrielvfonseca/replica/blob/main/docs/BENCHMARKS.md) .\n- **2026-10-25, quiet machine** (previous harness, 1,842 files):`replica new` 66 ms,`git clone` + setup 3.10 s,`cp -c` 1.33 s. Different harness and\nfixture; not directly comparable to the 2026-11-09 run.\n\nReplica adds APFS metadata per file per clone (~1.4 MB for a 1,700-file project\non a quiet machine); data blocks are shared with the base and changed files cost\nreal space as the agent works. The [replica-benchmarks skill](https://github.com/gabrielvfonseca/replica/blob/main/skills/replica-benchmarks/SKILL.md) lists what a clean run needs.\n\n```\nmake help              # every target\nmake check             # fmt, clippy (warnings are errors), and tests; what CI runs\nmake bench             # benchmark suite\nmake dist              # release binaries in bin/\n```\n\nCI runs on GitHub Actions macOS runners. [CONTRIBUTING.md](https://github.com/gabrielvfonseca/replica/blob/main/CONTRIBUTING.md) covers the workflow, and [AGENTS.md](https://github.com/gabrielvfonseca/replica/blob/main/AGENTS.md) holds the rules for coding agents. The [replica-dev skill](https://github.com/gabrielvfonseca/replica/blob/main/skills/replica-dev/SKILL.md) describes the code layout.\n\n| [CLI](https://github.com/gabrielvfonseca/replica/blob/main/docs/CLI.md) | Every command, flag, output, and exit code | \n| [SPEC](https://github.com/gabrielvfonseca/replica/blob/main/docs/SPEC.md) | Problem, goals, non-goals, requirements | \n| [ARCHITECTURE](https://github.com/gabrielvfonseca/replica/blob/main/docs/ARCHITECTURE.md) | Components, layout, and flows | \n| [DATA_MODEL](https://github.com/gabrielvfonseca/replica/blob/main/docs/DATA_MODEL.md) | SQLite schema, state machine, migrations | \n| [DISK_SAFETY](https://github.com/gabrielvfonseca/replica/blob/main/docs/DISK_SAFETY.md) | Quotas, TTL, eviction, caches, and what deleting frees | \n| [BENCHMARKS](https://github.com/gabrielvfonseca/replica/blob/main/docs/BENCHMARKS.md) | Methodology, results, and corrections | \n| [benchmarks/](https://github.com/gabrielvfonseca/replica/blob/main/benchmarks/README.md) | The benchmark suite and fixture project | \n| [skills/](https://github.com/gabrielvfonseca/replica/blob/main/skills/README.md) | Agent skills: usage, base, maintenance, development, benchmarks, release | \n| [ROADMAP](https://github.com/gabrielvfonseca/replica/blob/main/docs/ROADMAP.md) | Shipped work, next steps, open questions | \n| [CHANGELOG](https://github.com/gabrielvfonseca/replica/blob/main/CHANGELOG.md) | Notable changes by version |", "url": "https://wpnews.pro/news/show-hn-100ms-copy-on-write-workspaces-for-ai-agents-on-macos", "canonical_source": "https://github.com/gabrielvfonseca/replica", "published_at": "2026-11-18 22:51:02+00:00", "updated_at": "2026-11-18 23:15:39.213549+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-infrastructure"], "entities": ["Replica", "Gabriel V. Fonseca", "macOS", "APFS", "Claude Code", "Cursor", "GitHub Copilot", "Aider"], "also_reported_by": [], "takeaway": "Replica cuts per-agent workspace setup of a 1,700-file project to about 100 ms at N = 1 and about 230 ms at N = 10 concurrent workspaces by cloning a pre-installed base with one clonefile(2) call instead of running git clone plus an install.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/show-hn-100ms-copy-on-write-workspaces-for-ai-agents-on-macos", "markdown": "https://wpnews.pro/news/show-hn-100ms-copy-on-write-workspaces-for-ai-agents-on-macos.md", "text": "https://wpnews.pro/news/show-hn-100ms-copy-on-write-workspaces-for-ai-agents-on-macos.txt", "jsonld": "https://wpnews.pro/news/show-hn-100ms-copy-on-write-workspaces-for-ai-agents-on-macos.jsonld"}}