Worktree Broker for Unity
Works with git worktrees of one repository: commits only explicitly named paths through a private per-checkout index (commit_paths, never pushing), previews merges of several worktrees' saved state onto main using git objects only via integrate, publishes/previews sync snapshots and three-way merges, and reports worktree freshness/drift against main with safe merge or refusal.
Brokers a single Unity 6 editor for many git worktrees: applies a worktree's stylesheets and [MethodReload]-tagged C# view methods to the running game (ui_live_reload/ui_revert), renders UI captures at any resolution or returns layout facts, holds an editor lease for multi-step sequences like Play mode stepping, and reports the main editor's compile status and broken files.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Worktree Broker for Unity
The Worktree Broker for Unity is an MCP server, a small Unity package and a desktop dashboard. Together they let several AI coding chats, each in its own git worktree of one Unity project, share one open Unity editor without getting in each other's way. Only the main checkout opens Unity. Each worktree chat gets a narrow, locked set of tools that check and show its work in that editor, and nothing it does there writes to the main checkout's files.
Status: 0.1.0, the first public release. Tested on Windows 11 with Unity 6000.4. Possibly rough edges on other setups
Who it's for
It's for a developer who runs several Claude Code or Codex chats at once on one Unity project, each in its own git worktree, and can't afford one editor per worktree. A Unity 6 editor often needs 2-3 GB plus most of a gigabyte per asset import worker, and a fresh worktree's first import is slow, so a few editors can exhaust a 32 GB machine.
What it's good for
Live UI reloads from a worktree. A worktree chat edits a
.ussstylesheet, or the body of a C# view method tagged[MethodReload], then callsui_live_reload. The running game in the main editor picks up the change in memory and the chat gets a screenshot back, usually in 0.25 to 2 seconds of editor time.ui_revertundoes it. The main checkout's files are never written.Captures.
ui_capturerenders the game's UI at any resolution while the editor is unfocused or the desktop is locked. It can crop to a region or a named element, or return only the layout facts (bounds, classes, fonts, text), which costs far fewer tokens than a full image.An editor lease for multi-step work. Each editor call takes a lock.
editor_leaseholds the editor for a sequence (enter Play mode, step frames, capture, exit), so another chat's call can't land halfway through. It runs out on its own when idle.Verify and compile checks without a second editor.
verifyruns your configured checks (for example a compile of every assembly against Unity's DLLs, ordotnet test) on a worktree, two at a time across the machine, and returns parsed errors.editor_compile_statusreports the main editor's last compile and names the broken files. You supply the checks: the broker runs them and parses their output.Safe commits in a shared checkout.
commit_paths(orpython commit.py -m "..." -- <paths>) commits only the paths you name, through a private index, one commit at a time per checkout. Another chat's staged files are never swept in. It never pushes.The integrate preview.
integratemerges several worktrees' saved state onto main using git objects only (no checkout, no index, no branch is moved) and reports conflicts.ui_live_reloadwithintegrationthen shows the combined UI in the main editor.Worktree drift.
worktree_freshnesssays how far a worktree is behind main and whether its changes overlap main's uncommitted work.worktree_updatedoes a safe merge or refuses.The dashboard. A Tk window shows every worktree, which chat is running or waiting for you, who holds the editor, the last compile, Unity and player memory, and token use per worktree and chat, read from local transcripts.
What it's NOT good for
One developer with one chat. Use Unity's own MCP server directly. The broker only pays off when several chats compete for one editor.
Projects that aren't Unity. Everything is built around a Unity editor, Unity MCP and Unity's Pipeline package.
macOS and Linux. It's Windows only for now:
msvcrtfile locks,NtQuerySystemInformation,taskkill, Win32 window APIs and pywin32 counters.Big scene, prefab or asset edits from a worktree. Only two things reach the running editor live: stylesheets that already exist in the main project, and bodies of already-tagged C# methods reloaded through Pipeline. New files, new fields, signature changes, UXML, scenes, prefabs and imported assets need a normal import or compile in the main checkout, which means merging the worktree's branch first.
Two editors in Play mode at once. There is one editor, and one chat at a time drives Play mode (through the lease). For networked play, test with built players instead (the
playerroute can run one).Worktree changes only reach the main editor through the broker's routes. Those are live reload, captures,
verify(which runs outside the editor), sync snapshots and the integrate preview. Everything else reaches it the normal way: merged into the main checkout's development branch. A worktree chat has no general editor control; only the main checkout's chat gets the full Unity MCP tool set.A Unity project in a subfolder of the repository.
Assetshas to be at the repository root.
Related MCP server: chat-room
Requirements
Windows 10 or 11.
Python 3.12 or later (3.13 tested) with
pip install -r requirements.txt(mcp1.29,psutil,websockets,pywin32).git, and uv for
uvx, which starts Unity's MCP server (mcpforunityserver==10.3.0).Unity 6 (tested on 6000.4) with the Unity project at the repository root, the
com.coplaydev.unity-mcppackage (keep it matching the pinned server) and this repository'sunity-package/(com.worktreebroker.unity).Optional:
com.unity.pipeline(0.10.0-exp.1 or later) for C# view reload. Without it, only stylesheets reload.An MCP client: Claude Code or Codex. Other MCP clients can call the tools, but chat state on the dashboard comes from Claude Code and Codex hooks.
Quick start
Every path below comes from your own machine: install.py writes the configs from the Python that runs it and from
where this folder sits, and never needs editing by hand. Run it with the Python you installed requirements.txt into.
Put this folder in your Unity repository's main checkout, for example at
tools/WorktreeBroker, and runpython -m pip install -r requirements.txt. A git submodule keeps it updatable:git submodule add https://github.com/Cheesewizard/WorktreeBroker.git tools/WorktreeBroker. The broker then treats the superproject (your game) as the project, and changes to the broker itself are committed inside the submodule.Add the Unity package to
Packages/manifest.json:"com.worktreebroker.unity": "file:../tools/WorktreeBroker/unity-package"(seeunity-package/README.md).python install.py config. It writesroutes.json(the main route is the checkout this folder is in, pinned to the branch it's on now) and a minimalproject.json, and keeps files that already exist. Both are optional: withoutroutes.jsonthe broker works out the same main route by itself, and withoutproject.jsonit runs with defaults.Register the broker with your chats. Both commands point at the main checkout's copy of
broker.py, so every worktree runs the same broker code:Claude Code:
python install.py claudewrites the broker into the main checkout's.mcp.json, and the hook that refuses direct Unity MCP calls into.claude/settings.json. Only the broker's own entries are replaced.Codex:
python install.py codexwrites each worktree's.codex/config.toml(broker on, direct Unity MCP off) and keeps any that exist.
Open the main checkout in Unity, then start a chat (or reopen a running one) and call
worktree_capabilities. It says which route the chat is on and how to check its work there.Optional:
python install.py claude-hooksprints the Claude Code hooks that give the dashboard each chat's state (--writemerges them into~/.claude/settings.jsonand keeps a.bakcopy). Then double-clickOpen Dashboard.cmd: it uses thepythonwnext to the Python that ran the installer, then thepylauncher, thenpythonwon PATH.Optional: add your own
verifychecks toproject.json(Bring your own compile check, andproject.example.json).
Setup and configuration has the details, Reference says what the broker costs each chat in context, and "Known limitations" below lists what isn't done yet.
The problem it solves
A Unity project is developed by several AI chats in parallel, each in its own git worktree so they don't overwrite each other's files. The obvious way to let each chat check its work in Unity is to open one editor per worktree, but each editor costs gigabytes of memory and a slow first import, so that stops scaling after a few worktrees.
The broker keeps one editor (the main checkout named in routes.json) and gives every chat a safe, narrow way
to use it:
Problem | What the broker does |
Too many Unity editors | Only the main checkout opens Unity. Worktree chats get tools instead of an editor. |
Calls going to the wrong editor | Every editor call is pinned to the main checkout's exact |
Two chats driving the editor at once | Editor calls take a shared lock, so one chat's calls never land in the middle of another's. |
Worktrees can't see their UI changes |
|
Sharing unfinished work between worktrees |
|
Seeing several worktrees' UI at once |
|
Running a bot match from a worktree |
|
Knowing what all the chats and windows are doing | A live dashboard lists worktrees, AI chat state, Unity windows and memory. |
How it is wired
The broker is an MCP server (broker.py). Each worktree's Codex config (.codex/config.toml) starts it with
--worktree <path> and turns direct Unity MCP off for that worktree, so the broker is the only way in. What a
session can do depends on its route (routes.json):
Route | Worktree | Tools |
| The main checkout named in | Every Unity MCP tool (pinned and locked), plus the shared tools below. |
| Any other worktree of the project (registered or not) | Shared tools: |
| A worktree with a player route |
|
Shared tools on every route: broker_status, worktree_capabilities, worktree_target, sync_publish, sync_list,
sync_preview, integrate, integrate_status, integrate_list. ui_live_reload, ui_revert and ui_capture are on the editor and source routes.
Start any session by calling worktree_capabilities: it says which route you're on and how to verify your work there.
Documentation
Page | What's in it |
Setup details, | |
| |
Pinning, the lock and time limits, the editor lease, compile status, the activity log, the idle Play mode guard | |
| |
Pages, chat states, the editor line, machine headroom, the Usage page | |
The player route: | |
Token cost, tool annotations, troubleshooting, every file | |
The editor side: install, parts, Pipeline toggles | |
The prototype player patcher and its bridge |
Known limitations
Every chat's broker on the main route starts its own Unity MCP server through
uvx: about 300 MB per chat, counting uv and the Python helpers. Sharing one server over HTTP is possible (the server supports--transport http) but isn't done yet.Windows only: file locks use
msvcrt, the process table usesNtQuerySystemInformation, hung children are ended withtaskkill, and the dashboard uses Win32 window APIs and pywin32 counters. A port needs a replacement for each.The Unity project must be at the repository root (
Assetsat the top). A project in a subfolder is refused with a message.Live reload covers stylesheets that already exist in the main project and bodies of
[MethodReload]methods already compiled into the main editor. Everything else a worktree changes reaches the main editor only once it is merged into the main checkout.verifyruns checks you configure. The broker ships no compile check of its own (see Bring your own compile check).The test suite is small (
python -m pytest):integrate,install.py,commit.py --untrackand the default routes. The other tools have no automated tests yet.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Git collaboration for AI agents and people: tasks, hand-offs, reviews, teams, shared memory.
Source control for coding agents: declare an intent, settle overlaps before code, verify each push.
Keeps AI coding agents on one codebase from overwriting each other, and briefs each on its code.
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceLocal coordination for coding agents that share a Git working tree.5 npm2MIT
- AlicenseNot gradedqualityDmaintenanceProvides a local chat room for coordinating work across Git worktrees, coding agents (Claude, Codex), and humans, with tools to start, wake, stop, message, and search agent sessions.Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables multiple AI coding agents to safely collaborate in the same git working tree by managing file ownership, merging writes, and preventing snapshot races.3 npm2MIT
- AlicenseNot gradedqualityAmaintenanceEnables coordinating Claude Code and Codex across separate Git worktrees with shared issue ownership, file reservations, messages, and explicit handoffs.144 PyPI3MIT