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 Scope and routing Run repository commands only from a [trusted checkout](../../docs/contributor verification.md trust boundary); even verify local.py help and list load repository code. [Choose verification for the change](../cmux testing/references/local vs ci validation.md) 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: 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](references/tagged builds.md). 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](../cmux testing/references/local vs ci validation.md) 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](../cmux architecture/references/swift 6 0 compatibility.md). 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](references/xcode project normalization.md). 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](references/sidebar extension tagging.md).

cmux-dev-workflow