Two agents in one Unity checkout will overwrite each other's work and fight over one editor. unity_worktree_create gives each of them a branch, a folder and a headless editor of its own, in a single call.
// one call: branch the project, boot an editor in it unity_worktree_create(name: "shield-rework", launch: "headless-graphics") → .sspace/agent-worktrees/shield-rework on agent/shield-rework // every other tool takes that path and works there unity_open_scene(project_root: WT, scene_path: "Assets/Arena.unity", enter_play_mode: true) unity_exec_patch(project_root: WT, code: "...") unity_screenshot(project_root: WT) // back in your checkout, when it works git merge agent/shield-rework
Running several agents on one Unity project sounds like a scheduling problem and turns out to be a filesystem problem. Two agents editing the same files produce a merge you never asked for. Worse, they share one editor: agent A enters Play Mode while agent B triggers a recompile, and both get results that describe neither change.
A git worktree solves the first half. Unity's Library folder, which is expensive to rebuild and unsafe to share, is why people usually stop there. Copy-on-write cloning solves the second half.
unity_worktree_create(name, kind, launch) is one tool call, and by the time it returns the agent has somewhere to work:
.sspace/agent-worktrees/<name> on branch agent/<name>. The prefix means these branches can never collide with the ones the app creates for you.git worktree add alone would hand the agent your last commit and none of today's work.Library folder seeded copy-on-write where the filesystem supports it, so the editor boots with assets already imported instead of spending minutes re-importing them.Library to seed from, because Unity imports the project from scratch. The call blocks until the editor's heartbeat arms or 300 seconds pass, so the agent knows which it got.A full worktree is the whole project: every asset, your uncommitted changes, the seeded Library. This is what you want when an agent is changing a game that already exists.
A settings worktree is a sparse checkout of ProjectSettings/ and Packages/ with an empty Assets/ folder. The Unity version, the render pipeline, the input system, the package set: all identical to your project. Nothing else. It is the sandbox to hand an agent that is building something from scratch, or reproducing a bug without your 40 GB of art in the way. The first boot only imports packages, so it is quick.
A branch is only half the point. The worktree has its own editor, so the agent can run the game in it: every tool on the Unity MCP server takes the worktree path as project_root and operates there instead of in your session.
That means the agent opens a scene, enters Play Mode, runs a TddScenario, patches C# into the running session, reads the console and takes a screenshot, all inside its own copy. Your editor keeps streaming your game the entire time, and nothing the agent does can stop your Play Mode or dirty your scene.
Launch modes match what the work needs. headless-graphics runs -batchmode with a real GPU device, so screenshots and camera captures work. headless-nographics is the cheapest option and refuses the visual tools outright rather than returning a black frame. Both are described in headless Unity modes.
Everything lives under .sspace/, which is gitignored. Worktrees do not appear in the app's file tree, do not turn up in search results, and do not show in the parent checkout's git status. You will not accidentally commit an agent's half-finished branch because you could not see what was in the diff.
unity_worktree_list reports the worktrees that exist and the health of each one's editor. unity_worktree_remove deletes a worktree and its branch, and refuses when that branch still has commits the parent's HEAD has not merged. Losing an agent's afternoon to a cleanup command is a bad way to learn that lesson.
There is nothing custom here on purpose. The work is on agent/<name>, so git merge agent/<name> from your checkout brings it in, and every tool you already use for review, blame and history works on it. If you would rather look before merging, open the worktree as a project of its own and press Play.
Agents are not the only ones who get a worktree. The launch screen can start any session in a fresh one, so two agents you supervise yourself never share a checkout either. That path uses the same machinery, with one difference: removing a worktree from the app moves it to the OS trash rather than deleting it outright.
.sspace/agent-worktrees/Gitignored, hidden from the file tree and search, absent from the parent's git status.
agent/<name>Namespaced so it cannot collide with the branches the app creates. An orphaned branch of the same name is adopted, not rejected.
Copy-on-write seedReflink clone where the filesystem supports it, a plain copy otherwise, and a from-scratch import if there is nothing to seed.
One per worktreeheadless-graphics or headless-nographics, each on its own control-socket slot. Idle editors quit after about ten minutes.
A git worktree of your project at .sspace/agent-worktrees/<name>, on branch agent/<name>, with its own headless Unity editor. The agent works and tests there; you merge the branch.
Yes. Every Unity MCP tool takes the worktree path as project_root, so opening a scene, entering Play Mode, running a scenario, patching C# and taking screenshots all happen inside the worktree's own editor.
Not for a full worktree with a Library to seed from: the seed is copy-on-write where the filesystem supports it. A worktree with nothing to seed from imports from scratch on first boot, which can take minutes.
Yes, for a full worktree. git worktree add on its own would give the agent your last commit, which is usually not the code you are asking about, so the working state is synced over. Library, Temp, Logs and .sspace are left out.
git merge agent/<name> from your checkout. Removal refuses while the branch still holds unmerged commits.
Yes. It is an ordinary Unity project on disk, so you can open it in Satura Space or in Unity Hub and press Play before deciding whether to merge.
unity_worktree_create, _list and _remove, with the 24 other tools that target them.
Headless UnityThe two modes a worktree editor boots in, and what each one can do.
TddScenarioHow an agent proves the change works before you merge its branch.
A branch, a folder and a running editor per agent, so parallel work stops meaning parallel damage.