robloxstudio-worktree
robloxstudio-worktree gives every Git worktree an isolated runtime consisting of:
- a complete worktree-local
.rbxlartifact; - a dedicated Rojo server on a deterministic free loopback port;
- an explicitly owned Roblox Studio edit process;
- routing to that exact process through a shared Roblox Studio MCP server;
- optional project validation and runtime-test commands.
It does not create or manage Git worktrees. It composes with plain
git worktree, a worktree manager, a human terminal, or an agent. The runtime
tool is intentionally independent of Codex; an agent integration only needs to
invoke the same CLI a developer uses.
Install and use
Published releases provide native archives for Linux/WSL, Windows, Intel
macOS, and Apple Silicon macOS. Download the archive for the host, verify it
against SHA256SUMS, and place robloxstudio-worktree (or
robloxstudio-worktree.exe) on PATH. The archives also carry the required
third-party notice and exact Rojo source patch.
After the crate is published, Rust users can alternatively install it with:
During development, install the native binary from this repository:
Native archives let workers use the CLI without Rust, Python, or a
package-manager runtime installed. Release maintainers should follow
RELEASING.md.
Add robloxstudio-worktree.json to a Roblox repository and ignore
.worktree-studio/. Then, from any worktree:
bootstrap runs repository-supplied setup commands and installs the bundled
managed Rojo plugin. Restart open Studio windows after the plugin changes.
test leaves the edit session open by default so the next iteration is fast;
pass --close when the worker is finished.
The CLI requires Rojo, Roblox Studio, and a running robloxstudio-mcp server.
Building from source requires Rust 1.85+. Windows, WSL-hosted Windows Studio,
and macOS plugin locations are supported. The safe process fallback for the
current MCP local launch limitation is Windows-specific; other platforms
require MCP to close the instance successfully.
Project contract
The checked-in contract is the whole project-specific seam:
Only version and project are required. The Rojo project's own name is
used unless name is set in this contract. Unknown fields fail closed so a
misspelled ownership or test setting cannot silently weaken isolation.
Serve modes
full serves the generated full project. It is the default and suits
source-only Rojo repositories.
source-overlay first builds the complete place, then removes named
place-preserved children from the live serve project and sets
$ignoreUnknownInstances at the corresponding service seams. Use it when
binary .rbxm map or asset roots must be present in the local place but should
not be reconciled continuously. Changes to preserved roots require
robloxstudio-worktree up --fresh; normal source changes continue to live-sync.
Migrating an existing experience
A worktree place that opens successfully can still be unsuitable for feature testing if it omitted experience settings, runtime animation graphs, character templates, or binary asset identity. Rojo full-place builds and Rojo live reconciliation have different safety properties, especially for MeshParts and other binary-backed instances.
See MIGRATION.md for the recommended inventory and extraction workflow, source-overlay preserve rules, animation and avatar parity checks, source-place cleanup precautions, troubleshooting guide, and two-worktree acceptance checklist.
Command placeholders
Bootstrap and hook command arrays support:
{root},{project},{state_dir}, and{artifact};{worktree_id},{instance_id}, and{mcp_url};- a standalone
{args}item in the test hook, expanded to arguments followingrobloxstudio-worktree test --.
Commands run directly with the repository root as their working directory; they are not interpreted by a shell.
bootstrap.plugin is "bundled" by default, may name a repository-relative
plugin file, or may be null when plugin installation is managed externally.
Ownership model
The generated place carries a random session token, worktree identity, unique project name, and loopback Rojo endpoint. Studio discovery accepts only an edit instance presenting all four values. On Windows and WSL, teardown prefers the exact recorded Studio PID after revalidating the complete in-place contract; this avoids ambiguous MCP association for asynchronous local-file launches. Other platforms use MCP close, with the same validated process fallback when available. Place-name similarity is never enough to adopt or stop a process.
Generated state lives only under .worktree-studio/. One shared MCP server can
route multiple worktree Studio processes because every operation includes the
exact instance_id; each worktree still owns its own Rojo process and port.
Managed Rojo plugin
The bundled plugin is Rojo 7.7.0 plus a narrow patch that reads the generated
loopback endpoint, verifies the exact project name, accepts the first managed
patch, and writes a non-archivable connection marker. Manual Rojo behavior is
unchanged. Source and license details are in
THIRD_PARTY_NOTICES.md.
The desired upstream end state is for stock Rojo to support an authenticated
or place-declared loopback endpoint and for robloxstudio-mcp to return an
asynchronous launch handle with process ownership and terminal failures. Once
those exist, the package can delete its plugin patch and Windows process
fallback without changing the project contract or worker commands.
Agent skill
A Codex-compatible operational skill is included at
skills/robloxstudio-worktree/SKILL.md.
It teaches agents how to create or resume feature worktrees, operate the exact
Studio/Rojo/MCP lifecycle, protect source-place behavior parity, coordinate
parallel feature workers, and retire worktrees without losing changes.