cmux Dev Workflow
cmux-dev-workflow
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.
SKILL.md
Full skill instructions
cmux Dev Workflow
Scope and routing
Run repository commands only from a trusted checkout;
even verify-local.py --help and --list load repository code.
Choose verification for the change
before preparing a native build. Fast feedback starts with
python3 scripts/verify-local.py; portable-tooling and documentation changes use
their scoped checks without an unrelated app build.
For native app or build-input changes, build with a tag as below. Setup (./scripts/setup.sh) initializes
submodules, builds GhosttyKit and installs the project-normalization hook;
it is not a prerequisite for portable static checks.
Tagged local development
When local native execution is authorized:
./scripts/reload.sh --tag <short-tag>
CMUX_TAG=<short-tag> scripts/cmux-debug-cli.sh list-workspaces
Reload builds without launching; add --launch when live verification is needed.
Never use bare xcodebuild or open an untagged cmux DEV.app: tags isolate bundle
IDs, sockets and build output from other sessions. Do not use /tmp/cmux-cli,
which follows the most recently reloaded app. See tagged builds.
Never quit, kill, relaunch or xctrace --launch the user's running cmux
(com.cmuxterm.app); it holds their live agent sessions.
An app build does not establish test-target compilation or execution. Follow the test guide for those claims.
Toolchain and project files
.xcode-version owns the Xcode major; cmux.xcodeproj/project.pbxproj currently
uses objectVersion 60. The Intel/macOS 14 fallback uses Xcode 16.2/Swift 6.0;
keep app-linked code compatible as specified in
Swift 6.0 compatibility.
The installed pre-commit hook normalizes staged project files and registers new
Python tests in tests/test-execution.toml. Preserve it and
run python3 scripts/verify-local.py --only project after project edits. Toolchain
pin changes are deliberate team decisions; see project normalization.
Sidebar extension tags
Keep the extension-point ID, bundle-ID suffix and display-name suffix distinct
for each tag. Build extensions through scripts/reload-extension.sh --tag <tag>
with the matching host; do not repair a mismatched tag by re-signing. The exact
settings, helper arguments and verification checklist live in
sidebar extension tagging.