robloxstudio-worktree 0.1.0

Own an isolated Rojo, Roblox Studio, and MCP runtime for each Git worktree
Documentation

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:

cargo install --locked robloxstudio-worktree

During development, install the native binary from this repository:

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.

Add robloxstudio-worktree.json to a Roblox repository and ignore .worktree-studio/. Then, from any worktree:

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:

{
  "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 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.

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.