cmux Agent Rules

A terminal for working with coding agents on macOS.

Overview

cmux gives every development build its own app name, socket, and build folder so it cannot control the user's main app. It also warns where tests miss real terminal behavior and points component work to dedicated skills. AGENTS.md links to this CLAUDE.md file.

Behavioral framing Hard prohibitions Verification by change type Pointing at the source of truth

Documents

├── 
├──  · symlink → CLAUDE.md
├── .github
│   └── review-bot-rules
│       └── 
├── cmux-browser
│   └── 
├── cmux-tui
│   ├── 
│   └── 
├── ios
│   ├── 
│   └── 
├── Packages
│   └── iOS
│       ├── 
│       └── 
├── skills
│   ├── *
│   │   └── SKILL.md — Task-specific contributor skills
│   └── cmux-browser
│       └── 
└── web
    ├── 
    └──  · imports AGENTS.md

Techniques in this file

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.

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 requires a tag and strips inherited terminal identifiers before selecting that build's socket. It never depends on whichever build ran most recently.

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.

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.

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.

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.

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.

Ideas for your repo

Isolate runtime identifiers as well as build output in parallel development.
Make control helpers reject an unspecified target and scrub inherited routing context.
Verify that added test files are actually part of the test target.
Reproduce platform-sensitive failures on the reported operating-system version.
Route UI and CLI entry points through the same action implementation.