| name | cmux-dev-workflow |
| description | Contributor workflow rules for cmux setup, Xcode project normalization, tagged sidebar ExtensionKit development, and dev builds. Use when setting up the cmux repo, changing Xcode project files, adding sidebar extensions, or working with tagged debug builds. |
cmux Dev Workflow
Tagged local dev
After making code changes, always run the reload script with a tag to build the Debug app:
./scripts/reload.sh --tag <short-tag>
By default, reload.sh builds but does not launch the app. Pass --launch only when you need to open it automatically.
Never run bare xcodebuild or open an untagged cmux DEV.app. Untagged builds share the default debug socket and bundle ID with other agents, causing conflicts and stealing focus.
For CLI or socket dogfood against a tagged Debug app, use the tag-bound helper and set CMUX_TAG:
CMUX_TAG=<tag> scripts/cmux-debug-cli.sh list-workspaces
Do not use /tmp/cmux-cli for tagged dogfood. That symlink points at the most recently reloaded build.
When rebuilding cmuxd for release/bundling, always use ReleaseFast:
cd cmuxd && zig build -Doptimize=ReleaseFast
Initial setup
Run the setup script to initialize submodules, build GhosttyKit, and install the pbxproj normalization pre-commit hook:
./scripts/setup.sh
Xcode toolchain
The team is pinned to Xcode 26.x. .xcode-version records the major; cmux.xcodeproj/project.pbxproj carries objectVersion = 60, which is what Xcode 26 writes by default. (objectVersion 77 is reserved for projects that adopt synchronized folder groups, which cmux does not use yet. Bumping to a different value requires a deliberate team decision.)
