cmux Architecture

Package architecture

cmux is migrating from a single app target into Swift Packages under Packages/. Every new package must be:

• Ergonomic. Default to internal access; public only what downstream consumers actually use.
• Acyclic. Packages form a strict DAG. Share a type by lifting it to a lower package or defining a protocol seam in the consumer. Every new dependency edge requires re-checking that the graph stays acyclic.
• Whole-domain. One package owns a full domain (settings, appearance, workspace, terminal, browser, command palette). CmuxAppearanceMath + CmuxAppearanceTheme + CmuxAppearanceSettings is folder structure inside CmuxAppearance, not module structure. A boundary exists because more than one consumer needs the contents, or a build/test seam must exist.

When in doubt, extract leaf-first: the package with no internal dependencies. Existing packages under Packages/ predate this policy; do not use them as design references.

Wiring a new package into cmux.xcodeproj needs explicit pbxproj entries in both the cmux and cmux-unit targets. See references/package-boundaries.md.

Group folders. Every package lives physically under exactly one group directory: Packages/Shared/<pkg> (both apps), Packages/iOS/<pkg> (iOS only), or Packages/macOS/<pkg> (macOS only). cmux.xcworkspace/contents.xcworkspacedata mirrors that folder shape, with three groups whose container locations are those folders and every package directory as a FileRef under its folder's group. The folder is the source of truth: to move a package, git mv the directory then run python3 scripts/check-workspace-package-groups.py --write. Cross-group .package(path:) deps use ../../<Group>/<Name>. Never hand-edit workspace group membership. CI runs python3 scripts/check-workspace-package-groups.py --check and fails on drift.

Lockfiles. Do not gitignore cmux-owned Package.resolved files; SwiftPM resolution changes must be visible in PR diffs. Track the root Xcode lockfile and every cmux-owned package-local Package.resolved produced by standalone swift package resolve / swift build / swift test. A package-local lockfile is the source of truth for that package's standalone resolution and is not replaced by cmux.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved. Vendored third-party directories may keep their upstream ignore policy. CI runs python3 scripts/check-package-resolved-policy.py.

Feature flags mean remote PostHog runtime flags. Unless the user explicitly asks for a compile-time flag, local setting, or environment variable, implement a feature flag through CmuxFeatureFlags with a PostHog key, an explicit unavailable fallback, registry metadata, live update behavior, and focused tests. A local override may support dogfood but must not be the production control plane.