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.