cmux centers its instructions on isolated development builds, explicit verification, and shared behavior across UI and CLI surfaces. A tag identifies the application, socket, and build output; companion helpers remove ambient terminal context before targeting that build. The guide also calls out ways a green test run can miss coverage and routes component work to contributor skills. AGENTS.md symlinks to this CLAUDE.md.
Quoted passages are verbatim. Open one to see it in the source.
01 / Behavioral framing
Isolate the complete development identity
The build tag controls more than the filename. It isolates the bundle ID, socket, and derived data, allowing development builds to coexist with the user's main application.
Source excerpt starting at line 16.
16A tag gives the app its own name, bundle ID, socket, and derived data path, so it runs side-by-side with the user's main app. Report the build to the user as a markdown link to `http://127.0.0.1:17320/<tag>`. Never put a `file://` URL, a raw `.app` path, or `/tmp/cmux-<tag>/...` in chat output.
02 / Hard prohibitions
Remove ambient routing state
The debug helper refuses an unspecified tag and strips inherited terminal identifiers before selecting the tagged socket. This makes the target explicit instead of depending on whichever build was launched most recently.
Source excerpt starting at line 51.
51The helper refuses to run without `CMUX_TAG`, targets `/tmp/cmux-debug-<tag>.sock`, and uses the matching tagged CLI from DerivedData. It scrubs ambient cmux terminal context (`CMUX_SOCKET`, `CMUX_SOCKET_PASSWORD`, workspace/surface/tab/panel IDs, cmuxd socket, debug log), then sets `CMUX_SOCKET_PATH`, `CMUX_BUNDLE_ID`, and `CMUX_BUNDLED_CLI_PATH` for the tag.
03 / Verification by change type
Expose the failing regression test in history
The instructions ask for the test and fix in separate commits so CI can show the transition from failure to success.
Source excerpt starting at line 112.
112Two commits, so CI proves the test catches the bug: commit 1 adds the failing test only (CI red), commit 2 adds the fix (CI green). This is visible in the PR Commits tab.
04 / Verification by change type
Check whether tests are wired into the target
The file describes a silent failure mode: a Swift test file can exist without Xcode project entries and a successful invocation can execute no tests. It names the guard that checks this wiring.
Source excerpt starting at line 136.
136- **Test wiring** (`cmux-testing`): a `.swift` file in `cmuxTests/` without a `PBXFileReference` + `PBXSourcesBuildPhase` entry is silently skipped, and both `xcodebuild test` and bot reviews pass with "Executed 0 tests". `workflow-guard-tests` runs `./scripts/lint-pbxproj-test-wiring.sh` to catch it.
05 / Verification by change type
Reproduce on the reporter's platform
A documented Foundation difference explains how maintainer machines can miss a bug affecting an older macOS release. The instruction makes the reporter's version part of reproduction.
Source excerpt starting at line 140.
140- **Foundation, SwiftUI, AttributeGraph, and WebKit semantics change between macOS major versions.** `URL(fileURLWithPath: "/").deletingLastPathComponent().path` returns `"/.."` on macOS 14 and 15 but `"/"` on macOS 26 (https://github.com/manaflow-ai/cmux/issues/4529); CI and maintainer machines were all on the fixed side while every reporter was on the broken side. Test on the reporter's macOS before declaring a repro disproven. AWS M4 Pro builders (`aws-m4pro-1..6`) run macOS 15.7.4.
06 / Pointing at the source of truth
Give all entry points one behavior owner
Shortcuts, menus, CLI, and settings must use the same action path. Optimistic updates also share one mutation path and reconcile against the authoritative result.
Source excerpt starting at line 144.
144When a behavior is exposed through multiple entrypoints (shortcut, command palette, context menu, CLI, settings, debug menu), implement one shared action path and verify every entrypoint. Do not patch one surface and leave the others with duplicated logic.
Put it to work
Borrow this for your repo
01Isolate runtime identifiers as well as build output in parallel development.
02Make control helpers reject an unspecified target and scrub inherited routing context.
03Verify that added test files are actually part of the test target.
04Reproduce platform-sensitive failures on the reported operating-system version.
05Route UI and CLI entry points through the same action implementation.
cmux's file tells an agent how the codebase works. It cannot tell it which bug three customers hit this week. Modem keeps that context current and attaches it to the work.
