# cmux Architecture

Sets Swift package layering, dependency rules and concurrency before edits.

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

## Install

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

## Description

cmux package architecture, refactor layering, dependency inversion, file organization, DocC documentation, package design discipline, testability, and Swift 6 concurrency rules. Use before adding or meaningfully rewriting Swift files, Swift packages, coordinators, services, repositories, or public package APIs.

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

# 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 `cmuxTests` targets (`cmuxTests` is what the `cmux-unit` scheme runs). See [references/package-boundaries.md](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.

The rest: https://github.com/manaflow-ai/cmux/blob/HEAD/skills/cmux-architecture/SKILL.md