Replica uses APFS clonefile to speed up AI agent workspaces on macOS
A new open-source tool creates isolated, fully installed project copies in milliseconds using macOS copy-on-write technology, solving slow environment setup for local AI agents.
Gabriel Fonseca released Replica, an open-source command-line tool that generates isolated, fully installed project workspaces for AI agents in milliseconds. Published on GitHub in November 2026, the utility leverages macOS-specific file system features to bypass the slow process of cloning repositories and installing dependencies repeatedly.
The tool targets developers running local AI coding agents, where the overhead of setting up a fresh environment often exceeds the time the agent spends actually working. By creating instant, disk-safe copies of a pre-built project state, Replica aims to make iterative agent workflows significantly faster and more resource-efficient on Apple hardware.
What happened
Fonseca introduced Replica as a solution to a specific bottleneck in local AI development: the creation and deletion of small files. Standard workflows involving git clone followed by package installation (such as npm ci) can take seconds or even minutes. This delay occurs because operating systems struggle with the high volume of metadata operations required to write thousands of small files to disk.
Replica changes this dynamic by building a single "base" workspace once. This base contains a full git checkout with all dependencies installed. When a new agent session is needed, the tool clones this base using the clonefile(2) system call. This operation creates a new workspace entry in the file system without copying the actual data blocks immediately. The data is shared with the base until a file is modified, at which point APFS (Apple File System) uses copy-on-write to duplicate only the changed blocks.
The project includes benchmarks performed on an Apple M1 Max machine running macOS 26.6. In these tests, creating a new workspace for a project with 1,700 files took approximately 100 milliseconds for a single instance. Even with ten concurrent workspace creations, the median time remained around 230 milliseconds. In contrast, a traditional git clone plus setup process took nearly four seconds under similar load conditions.
How it works
The core mechanism relies on APFS copy-on-write semantics. When replica new is executed, the tool makes a single system call to clone the metadata of the base directory. This results in a new directory structure that appears to be a complete, independent copy of the project. However, the underlying storage blocks are referenced from the original base. This allows the workspace to be ready for use almost instantly, as no heavy data copying occurs during initialization.
Each workspace functions as a standard git repository. Developers or agents can create branches, commit changes, and push to remote repositories without affecting the base or other workspaces. The tool manages disk usage through several strategies, including time-to-live (TTL) expiration, least-recently-used (LRU) eviction, and optional byte caps. It can also operate on a dedicated APFS volume with a quota to prevent accidental disk saturation.
To keep the base current, users can run replica base refresh. This command clones the existing base, fetches updates from the remote repository, and resets the copy. If the lockfile (such as package-lock.json) has not changed, the setup step is skipped entirely, making updates very fast. If dependencies have changed, it runs an incremental install. This approach ensures that the base remains fresh without requiring a full rebuild from scratch.
Key details
- Platform restriction: Replica works only on macOS with APFS volumes because it depends on the
clonefile(2)system call, which is not available on Linux or Windows. - Performance metrics: On an M1 Max, creating a workspace for a 1,700-file project takes ~100 ms (single) to ~230 ms (10 concurrent), compared to ~4 seconds for
git cloneplus install. - Disk efficiency: A new workspace adds only about 1.4 MB of metadata for a 1,700-file project. Actual disk space is consumed only when files are modified due to copy-on-write behavior.
- Git integration: Each workspace is a full git checkout capable of branching, committing, and pushing. The remote origin is inherited from the base configuration.
- Agent support: The tool provides a stable CLI with JSON output and includes skills for popular AI coding tools like Claude Code, Cursor, Copilot, Zed, and Aider.
- Concurrency safety: Tests demonstrate zero SQLite busy errors or corruption during simultaneous creation and removal of ten workspaces, with garbage collection safely skipping active sessions.
Why it matters
For engineers building products with AI agents, local iteration speed is critical. Agents often need to test hypotheses by modifying code, running builds, and checking results. If each iteration requires waiting minutes for environment setup, the feedback loop becomes painfully slow. Replica reduces this setup time to milliseconds, allowing agents to perform more trials in less time. This efficiency gain is particularly valuable for tasks that involve exploring multiple branches or testing different implementation strategies in parallel.
Additionally, the tool addresses resource management concerns. Running multiple agents simultaneously can quickly exhaust disk space if each maintains a full copy of the project and its dependencies. By sharing data blocks and implementing automatic cleanup via TTL and LRU policies, Replica keeps disk usage bounded. This makes it feasible to run several agent instances concurrently on a single developer machine without manual intervention to clear old workspaces.
What you can do
- Install Replica on your macOS machine using the provided installer script or by building from source with Rust.
- Create a dedicated APFS volume with a quota to host your replicas, ensuring that agent activities do not fill your main system disk.
- Build a base workspace for your project using
replica base build, specifying the repository URL and setup command. - Generate new workspaces for agent tasks using
replica new, optionally setting a TTL to automate cleanup. - Integrate Replica skills into your AI coding assistant (such as Cursor or Claude Code) to enable automatic workspace management.
- Monitor disk usage and base freshness with commands like
replica listandreplica base statusto maintain optimal performance.


