cd /news/ai-agents/show-hn-100ms-copy-on-write-workspac… · home › topics › ai-agents › article
[ARTICLE · art-172190] src=github.com ↗ pub= topic=ai-agents verified=true sentiment=↑ positive

Show HN: 100ms copy-on-write workspaces for AI agents on macOS

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.

key 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.

read10 min views8 publishedNov 18, 2026
Show HN: 100ms copy-on-write workspaces for AI agents on macOS
Image: Michielbdejong (auto-discovered)

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.

cd "$(replica new --ttl 2h --name fix-login)"   # a ready workspace; the path goes to stdout
git checkout -b agent/fix-login && git commit -am "fix login" && git push -u origin agent/fix-login
replica rm <id>                                 # done; or let the TTL expire

Agent workloads are dominated by creating and deleting small files (a checkout, node_modules, build output), and that's where macOS is slowest. A fresh install takes seconds to minutes before the agent does any work.

Replica builds a base once: a git clone with its dependencies installed. Each replica new clones that base with one clonefile(2) call. The data blocks stay shared with the base until a file changes, so the new workspace is ready almost at once. Measured on an Apple M1 Max, replica new of a 1,700-file project takes about 100 ms at N = 1 and about 230 ms at N = 10 concurrent workspaces, versus seconds for git clone plus an install. Numbers and methodology.

  • 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 forgit clone plus an install. Exact numbers vary with machine load; seedocs/BENCHMARKS.md for the full table and methodology.

  • Real git. Each workspace is a full git checkout. It can branch, commit, and push, and the base stays untouched.Details below .

  • Bounded disk. TTL expiry, least-recently-used eviction, a byte cap, and an optional dedicated APFS volume with a quota.

  • Cheap updates.replica base refresh brings the base up to date with its remote without a full rebuild.Details below .

  • Agent-ready. A stable CLI with--json output, documented exit codes, and skills for Claude Code, Cursor, Copilot, Zed and Aider.

  • Concurrency tested.tests/concurrency.rs runs 10 simultaneousreplica 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.

  • macOS on an APFS volume. Replica uses clonefile(2) , which Linux does not provide. Tested on macOS 26.6 (Apple M1 Max).

  • The base tree and every workspace must be on the same APFS volume . Clones cannot cross volumes, and Replica refuses rather than silently copying.

Binaries are published for macOS on Apple Silicon (arm64) and Intel ( x86_64). A universal binary covers both.


curl -fsSL https://raw.githubusercontent.com/gabrielvfonseca/replica/main/scripts/get-replica.sh | sh

git clone https://github.com/gabrielvfonseca/replica.git && cd replica
make release && PREFIX=$HOME/.local make install

Run replica help for a guided overview, or replica help quickstart to get started.

1. Choose a volume. A dedicated APFS volume with a quota is the safest setup, because clones can never fill your main disk.

diskutil apfs list                                   # find your APFS container
./scripts/setup-volume.sh disk3 100g Work            # creates /Volumes/Work, turns off Spotlight indexing there
export REPLICA_ROOT=/Volumes/Work/replica

Any APFS directory works too. Add REPLICA_MAX_BYTES to cap its size. See DISK_SAFETY for the trade-offs.

2. Build a base once.

replica base build --repo https://github.com/you/proj.git --setup "npm ci"
replica base check                                   # find build output that breaks when cloned

3. Create, use, and remove workspaces.

cd "$(replica new --ttl 4h --name feature-x)"        # path on stdout, status on stderr
eval "$(replica env <id>)"                           # per-workspace TMPDIR and shared caches
replica touch <id>                                   # keep a long session out of LRU eviction
replica list                                         # table; add --json for scripts
replica rm <id>                                      # remove one (idempotent)

Branches with different lockfiles. If you create a workspace from a branch whose lockfile differs from the base, use --ref:

replica new --ref my-feature-branch

Replica compares the branch's lockfile hash with the base's recorded hash. If they match, the workspace is cloned directly (cloned directly). If they differ, Replica clones the base, checks out my-feature-branch, then runs the setup command (an incremental install) so the workspace gets correct dependencies, and reports lockfile drift on branch my-feature-branch; running incremental install. The CLI always tells you which path it took.

4. Give your agents the skill.

npx skills add gabrielvfonseca/replica               # skills.sh CLI: all six skills
replica setup --dry-run                              # see what setup would write for Claude Code, Cursor, Copilot, Zed, Aider
replica setup                                        # write it

Yes. A workspace is a complete git repository, not a read-only copy:

Operation In a workspace Effect on the base
git checkout -b ,git commit Works. Commits live in the workspace's .git None
git push origin <branch> Works, to the remote the base was built from None
git pull ,git fetch Works None
git status ,git diff Works None

Things to know:

  • Remote credentials.push uses whatever credentials git uses on this machine (SSH keys, a credential helper). Replica does not add or store any.
  • The remote is the one you built from.origin in a workspace is the--repo you passed tobase build . If that is a local path, pushes go to that path.
  • Workspaces are independent. Two workspaces on the same branch will conflict on push, the same as two clones would. Use one branch per workspace.
  • 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.

For 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.

When the remote moves on, replica base refresh updates the base. It does not rebuild from scratch:

  1. Clonefiles the current base. This copies metadata only, so it is quick and uses almost no extra disk.
  2. Runs git fetch and resets the copy toorigin/HEAD . Only files that changed upstream are rewritten.
  3. Re-runs setup only if a lockfile changed . If none did, setup is skipped entirely.
  4. Swaps the new base in. Existing workspaces are unaffected, because each one owns its blocks.

So 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.

Check freshness with replica base status, and use replica new --require-fresh to refuse a stale base.

  • 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.
  • 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 anpm rebuild that rewritesnode_modules .
  • Deleting a workspace frees only the blocks no other file shares. A fresh workspace frees little, and a heavily changed one frees much more.

This is why the TTL, LRU eviction, and byte cap exist. DISK_SAFETY explains each one.

Spotlight 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.

  • 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. Runreplica base check to find them, then fix them with--post-clone or by regenerating them. See thereplica-base skill .
  • Cargo target/ clones safely but adds cost. A clonedtarget/ 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 buildtarget/ during setup, or add an exclusion option to your base build. A clonedtarget/ of a large project can add tens of MB of APFS metadata per clone, so exclude it if disk cost matters. A sharedCARGO_TARGET_DIR under$REPLICA_ROOT/cache keeps incremental builds fast but reintroduces Cargo's file-lock waiting, so parallel agents can block onBlocking waiting for file lock . For parallel use, considersccache instead of a shared target dir.
  • 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.
  • Same volume only. Source, base, and workspaces must share one APFS volume.
  • 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.
  • macOS only. Linux and Windows are out of scope.

The suite in benchmarks/ compares replica new with git clone plus install, git worktree plus install, pnpm with the global virtual store, and cp -c, and it also measures replica rm and replica base refresh, at concurrency N = 1, 5, and 10.

make release                                         # target/release/replica
make bench                                           # bundled fixture (~15 min)
make bench CONCURRENCY=1,5,10                        # parallel workspace creation

Full results, methodology, machine details, and exact commands are in docs/BENCHMARKS.md.

Headline (Apple M1 Max, macOS 26.6.2, under load, 1,739-file npm project):

Concurrency replica new median cp -c -R median git clone + setup median
N = 1 ~100 ms ~958 ms ~3.96 s
N = 10 (all at once) ~230 ms ~3.55 s ~4 s

replica new is about 15x faster than cp -c -R even with 10 concurrent workspaces, and tens of times faster than git clone plus an install. The one-time replica base build (~2–3 s) is less than a single git clone + setup, so Replica comes out ahead on the very first workspace.

  • 2026-11-09, under load (1-minute load 171–184 on 10 cores). These absolute times are inflated by the shared machine load; relative ordering held, but do not quote the ratios as settled. Exact numbers and P95 values are indocs/BENCHMARKS.md .
  • 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 fixture; not directly comparable to the 2026-11-09 run.

Replica adds APFS metadata per file per clone (~1.4 MB for a 1,700-file project on a quiet machine); data blocks are shared with the base and changed files cost real space as the agent works. The replica-benchmarks skill lists what a clean run needs.

make help              # every target
make check             # fmt, clippy (warnings are errors), and tests; what CI runs
make bench             # benchmark suite
make dist              # release binaries in bin/

CI runs on GitHub Actions macOS runners. CONTRIBUTING.md covers the workflow, and AGENTS.md holds the rules for coding agents. The replica-dev skill describes the code layout.

| CLI | Every command, flag, output, and exit code | | SPEC | Problem, goals, non-goals, requirements | | ARCHITECTURE | Components, layout, and flows | | DATA_MODEL | SQLite schema, state machine, migrations | | DISK_SAFETY | Quotas, TTL, eviction, caches, and what deleting frees | | BENCHMARKS | Methodology, results, and corrections | | benchmarks/ | The benchmark suite and fixture project | | skills/ | Agent skills: usage, base, maintenance, development, benchmarks, release | | ROADMAP | Shipped work, next steps, open questions | | CHANGELOG | Notable changes by version |

── more in #ai-agents 4 stories · sorted by recency
── more on @replica 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/show-hn-100ms-copy-o…] indexed:0 read:10min 2026-11-18 · —