# Cmux Dev Workflow

Contributor workflow for native cmux setup, tagged dev builds, Xcode project...

- Repository: https://github.com/manaflow-ai/cmux (28635 stars)
- Category: Mobile
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add manaflow-ai/cmux --skill cmux-dev-workflow -g -a claude-code -y`
Codex: `npx skills add manaflow-ai/cmux --skill cmux-dev-workflow -g -a codex -y`
Cursor: `npx skills add manaflow-ai/cmux --skill cmux-dev-workflow -g -a cursor -y`
Gemini CLI: `npx skills add manaflow-ai/cmux --skill cmux-dev-workflow -g -a gemini-cli -y`

## Description

Contributor workflow for native cmux setup, tagged dev builds, Xcode project normalization and sidebar extensions. Use for native build inputs, setup or tagged app verification.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

```sh
./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](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 rest: https://github.com/manaflow-ai/cmux/blob/HEAD/skills/cmux-dev-workflow/SKILL.md