mirage

name	mirage
description	Use when you need an isolated copy of a large repository — especially a Unity project — for an agent task, parallel work, or a risky experiment, and a full git worktree or plain copy is too expensive (slow, many GB of disk, or a forced Unity reimport). macOS/APFS only.

mirage

Overview

mirage makes near-free copy-on-write clones of a repo using APFS clonefile. A clone shares disk blocks with its source until written, so it costs ~0 bytes and ~1 minute even for a ~28 GB Unity project, yet is a fully independent git working copy: edits never touch the source, and Unity reuses the cloned Library/ (no reimport).

Reach for it instead of git worktree, which materializes the whole tree (GB of disk) and forces a Unity reimport. CLI is mirage (on PATH); full flags via mirage --help.

When to use

• Isolating an agent task or risky experiment on a large/Unity repo without touching the source.
• Running several parallel workspaces off one repo cheaply.
• You'd otherwise reach for git worktree / cp -r but it's too slow or too big.

When NOT to use: small or non-Unity repos where a worktree is already cheap; crossing filesystem volumes (clonefile can't); non-macOS or non-APFS systems.

Quick reference

Task	Command
Create a clone (Unity-ready)	mirage new <src> --name <name>
Create, code-only (lighter, Unity reimports)	mirage new <src> --no-library
Clone to an explicit path	mirage new <src> <dest>
List clones	mirage ls
Inspect one	mirage info <name>
Destroy one (deletes the tree + deregisters)	mirage rm <name> [-y]
Forget hand-deleted clones	mirage prune

<name> is the clone's directory under ~/.mirage/trees/ (the default location). Pass either --name <name> or an explicit <dest> path; if you pass both, <dest> wins.

Typical workflow

mirage new ~/projects/sample --name fix-bug   # ~1 min, ~0 disk
cd ~/.mirage/trees/fix-bug                     # <-- do ALL work here
# edit / build / test / git branch + commit + push as usual...
mirage rm fix-bug -y                           # when done

Set the agent's working directory to the clone path. Every file operation (read, write, edit, search, shell) then operates on the clone transparently — no wrapper or interception.

Behaviors to know

• Snapshot, not live. A clone is frozen at creation; later source changes do NOT flow in, and clone changes never flow back. If the source drifts a lot while you work, rebase your clone's branch onto it before opening the MR.
• Git is fully intact. The clone starts on the source's currently-checked-out branch with full history and remotes, so branching and git push work normally.
• No merge-back. mirage only makes clones. Integrate using normal git inside the clone (branch, commit, push, open an MR) — there is no mirage merge/sync command.
• Working tree, untracked files, and submodules ride along exactly as cloned — the project compiles without re-running make setup or submodule init (a clone is more complete than a fresh worktree).
• Same volume only. Source and clone must be on one APFS volume; mirage refuses with an error otherwise. Use an explicit <dest> elsewhere on that volume if the default won't do.
• Unity-ready by default. Library/ is included so Unity skips reimport. Use --no-library only when you will NOT open the clone in Unity (lighter, a bit faster).

Common mistakes

• Editing the source out of habit. After mirage new, cd into the clone — stop working in the original.
• du panic. du reports logical size (~full); real cost is only the blocks you change. A fresh clone is not actually consuming the source's full size.
• --no-library then opening Unity. That forces a full reimport — defaulting to Unity-ready is usually what you want.
• Hand-deleting with rm -rf. Prefer mirage rm so the registry stays consistent (or run mirage prune afterward).