# robloxstudio-worktree
`robloxstudio-worktree` gives every Git worktree an isolated runtime consisting of:
- a complete worktree-local `.rbxl` artifact;
- 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:
```bash
cargo install --locked robloxstudio-worktree
```
During development, install the native binary from this repository:
```bash
cargo install --path .
```
Native archives let workers use the CLI without Rust, Python, or a
package-manager runtime installed. Release maintainers should follow
[`RELEASING.md`](RELEASING.md).
Add `robloxstudio-worktree.json` to a Roblox repository and ignore
`.worktree-studio/`. Then, from any worktree:
```bash
robloxstudio-worktree bootstrap
robloxstudio-worktree up
robloxstudio-worktree test -- --scenario smoke
robloxstudio-worktree status
robloxstudio-worktree down
```
`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:
```json
{
"version": 1,
"project": "default.project.json",
"serve": {
"mode": "source-overlay",
"preserve": {
"Workspace": ["Map", "Terrain"]
}
},
"hooks": {
"validate": [
"tools/place-check",
"--instance-id", "{instance_id}",
"--mcp-url", "{mcp_url}"
],
"test": [
"tools/runtime-test",
"--instance-id", "{instance_id}",
"{args}"
]
},
"bootstrap": {
"commands": [
["rokit", "install"],
["rojo", "sourcemap", "{project}", "-o", "sourcemap.json"]
],
"requiredGlobs": ["roblox_packages/**/default.project.json"],
"plugin": "bundled"
}
}
```
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](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 following
`robloxstudio-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`](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`](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.