# The One Analogy to Keep & What to Read Next

> A short plain-English recap: cmux is a terminal window manager where every tab is a workspace, every split is a surface, the sidebar is a live dashboard, and the socket is the intercom agents use to talk to the app. What to look at next depending on whether you are building an agent integration, customizing the UI, or hacking on the terminal core.

- Repository: manaflow-ai/cmux
- GitHub: https://github.com/manaflow-ai/cmux
- Human wiki: https://grok-wiki.com/public/wiki/manaflow-ai-cmux-e789cf316a9a
- Complete Markdown: https://grok-wiki.com/public/wiki/manaflow-ai-cmux-e789cf316a9a/llms-full.txt

## Source Files

- `README.md`
- `CLAUDE.md`
- `Sources/CmuxConfig.swift`
- `Packages/CMUXAgentLaunch`
- `skills.sh`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:

- [README.md](README.md)
- [CLAUDE.md](CLAUDE.md)
- [Sources/CmuxConfig.swift](Sources/CmuxConfig.swift)
- [Sources/CmuxWorkspaceDefinition.swift](Sources/CmuxWorkspaceDefinition.swift)
- [Sources/SocketControlSettings.swift](Sources/SocketControlSettings.swift)
- [Sources/SidebarPortDisplayText.swift](Sources/SidebarPortDisplayText.swift)
- [Sources/Sidebar/SidebarState.swift](Sources/Sidebar/SidebarState.swift)
- [Sources/ExtensionSidebarWorkspaceRowView.swift](Sources/ExtensionSidebarWorkspaceRowView.swift)
- [Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/AgentLaunchSanitizer.swift](Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/AgentLaunchSanitizer.swift)
- [Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/HermesAgentHookConfig.swift](Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/HermesAgentHookConfig.swift)
- [skills/cmux/skill.md](skills/cmux/skill.md)
- [skills/cmux-browser/skill.md](skills/cmux-browser/skill.md)
- [skills/cmux-workspace/skill.md](skills/cmux-workspace/skill.md)
- [skills/cmux-settings/skill.md](skills/cmux-settings/skill.md)
- [skills/cmux-diagnostics/skill.md](skills/cmux-diagnostics/skill.md)
- [skills.sh](skills.sh)
</details>

# The One Analogy to Keep & What to Read Next

cmux is a macOS terminal app with four moving parts you need to keep in your head. Once the analogy clicks, every file, command, and setting finds its place. This page gives you that analogy, maps it to real source files, and then points you at the right corner of the codebase depending on what you want to do.

This page is for people who just opened the repository and want to know where to look next — whether they are writing an agent integration, tweaking the UI, or hacking on the terminal core.

---

## The Analogy

Think of cmux like a hotel.

| Hotel concept | cmux concept | Where it lives |
|---|---|---|
| The building | **Window** — a top-level macOS app window | `AppDelegate.swift`, `ContentView.swift` |
| A floor / suite | **Workspace** — one sidebar tab, groups related terminals | `Sources/CmuxWorkspaceDefinition.swift` |
| A room | **Pane** — a split container inside a workspace | `vendor/bonsplit` submodule (the `Bonsplit` package) |
| The desk / TV screen | **Surface** — the actual terminal or browser session | `Sources/GhosttyTerminalView.swift` |
| The lobby notice board | **Sidebar** — shows git branch, PR, cwd, open ports, and latest notification for every workspace | `Sources/Sidebar/`, `Sources/ExtensionSidebarWorkspaceRowView.swift` |
| The hotel intercom | **Socket** — Unix socket that lets agents, CLI, and scripts talk to the live app | `Sources/SocketControlSettings.swift` |

```text
Window
 └─ Workspace  (sidebar tab)
     ├─ Pane  (split container)
     │   ├─ Surface:terminal
     │   └─ Surface:browser
     └─ Pane
         └─ Surface:terminal
```

Every CLI command and socket message uses these four handle types — `window:N`, `workspace:N`, `pane:N`, `surface:N` — as its coordinate system. The short-ref style is the default; UUIDs are accepted as input but only printed on request.

Sources: [skills/cmux/skill.md](skills/cmux/skill.md), [Sources/CmuxWorkspaceDefinition.swift:1-50](Sources/CmuxWorkspaceDefinition.swift)

---

## The Four Concepts in Plain English

### Workspace = a sidebar tab for a project

A workspace is the unit you see in the left sidebar. Each entry shows the git branch it's on, any linked PR number and status, the current working directory, the listening ports (formatted as `:3000`, `:8080`, etc.), and the most recent notification text from any agent running inside it.

Workspaces can be defined statically in `cmux.json` (with a name, cwd, color, and layout) or created dynamically at runtime. The `CmuxWorkspaceDefinition` struct is the parsed form of the static config.

Sources: [Sources/CmuxWorkspaceDefinition.swift:1-37](Sources/CmuxWorkspaceDefinition.swift), [Sources/SidebarPortDisplayText.swift:1-17](Sources/SidebarPortDisplayText.swift)

### Surface = what you actually type into

A surface is a single terminal session or browser tab. Inside one workspace you can have multiple panes (created with splits), and each pane can hold multiple surfaces (horizontal tabs at the top of the pane). The Ghostty rendering engine drives each terminal surface; browser surfaces run a WebKit view routed through the same pane container.

Sources: [README.md:60-65](README.md), [skills/cmux-workspace/skill.md](skills/cmux-workspace/skill.md)

### Sidebar = a live dashboard, not just a nav panel

The sidebar is not just a list of workspaces you can click on. Every row is a real-time snapshot: it renders git metadata, PR status, listening ports, and notification badge counts. The row view (`CmuxExtensionSidebarWorkspaceRowView`) is an `Equatable` SwiftUI view that receives immutable value snapshots and closure action bundles — no direct store references — so it can skip body re-evaluation during high-frequency typing.

Sources: [Sources/ExtensionSidebarWorkspaceRowView.swift:1-55](Sources/ExtensionSidebarWorkspaceRowView.swift), [Sources/Sidebar/SidebarState.swift:1-16](Sources/Sidebar/SidebarState.swift)

### Socket = the intercom agents use

The Unix socket (default path `/tmp/cmux-debug-<tag>.sock` for tagged Debug builds, discoverable at runtime via `CMUX_SOCKET_PATH`) is how the CLI, agent skills, and external automation scripts communicate with the running app. Access is controlled by a `SocketControlMode` enum with five levels: `off`, `cmuxOnly` (only processes started inside cmux terminals), `automation` (any local process from the same macOS user), `password`, and `allowAll` (unsafe, no auth).

The socket threading policy matters for agent builders: high-frequency telemetry commands (`report_*`, `ports_kick`, status/progress/log updates) must not use `DispatchQueue.main.sync` — parse and deduplicate off-main, then push minimal mutations to main with `async`.

Sources: [Sources/SocketControlSettings.swift:9-54](Sources/SocketControlSettings.swift), [CLAUDE.md — Socket command threading policy](CLAUDE.md)

---

## The Configuration File

The single user-facing config file is `~/.config/cmux/cmux.json` (JSONC). The in-app watcher reloads it on save — no restart needed.

The `CmuxConfigFile` struct is the parsed representation:

```swift
// Sources/CmuxConfig.swift:10-39
struct CmuxConfigFile: Codable, Sendable {
    var actions: [String: CmuxConfigActionDefinition]
    var ui: CmuxConfigUIDefinition?
    var notifications: CmuxNotificationConfigDefinition?
    var newWorkspaceCommand: String?
    var surfaceTabBarButtons: [CmuxSurfaceTabBarButton]?
    var commands: [CmuxCommandDefinition]
    var vault: CmuxVaultConfigDefinition?
}
```

Top-level sections split into two groups:

| Section | Purpose |
|---|---|
| `app`, `terminal`, `notifications`, `sidebar`, `sidebarAppearance`, `workspaceColors`, `automation`, `browser`, `shortcuts` | **Settings** — live-reloaded app behavior |
| `actions`, `ui`, `commands`, `vault`, `rightSidebar` | **Definitions** — custom commands, palette entries, workspace layouts |

Terminal rendering (font, theme, cursor, background opacity, blur) goes in Ghostty config at `~/.config/ghostty/config`, not in `cmux.json`.

Sources: [Sources/CmuxConfig.swift:10-86](Sources/CmuxConfig.swift), [skills/cmux-settings/skill.md](skills/cmux-settings/skill.md)

---

## Agent Integration: What the Codebase Provides

cmux is designed to host AI coding agents. Three subsystems exist specifically for this:

### 1. Launch sanitizer (`CMUXAgentLaunch` package)

When an agent session is suspended and resumed, cmux needs to reconstruct a safe launch command without re-applying transient flags (like `--use-system-ca`) or non-restorable subcommands. The `AgentLaunchSanitizer` handles this for every supported agent kind: `claude`, `claudeTeams`, `codex`, `codexTeams`, `grok`, `amp`, `cursor`, `gemini`, `hermes-agent`, `rovodev`, `copilot`, and more.

Sources: [Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/AgentLaunchSanitizer.swift:24-68](Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/AgentLaunchSanitizer.swift)

### 2. Hook injection (`HermesAgentHookConfig`)

cmux can inject its own hook entries into an agent's config file (e.g. a YAML hooks section) and cleanly remove them on uninstall. The begin/end markers and base64-encoded restore lines let the injection be idempotent and reversible. The same pattern is used for `hermes-agent` and `rovodev`.

Sources: [Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/HermesAgentHookConfig.swift:1-90](Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/HermesAgentHookConfig.swift)

### 3. Skills (`skills/` directory + `skills.sh`)

Agent skills are bundled Markdown instruction files that teach agents how to drive cmux via the CLI and socket. They are installed into `~/.codex/skills/` (or a custom `--dest`) by `skills.sh`. Available skills:

| Skill | Purpose |
|---|---|
| `cmux` | Core topology control: windows, workspaces, panes, surfaces, focus, reorder |
| `cmux-browser` | Browser surface automation: open, navigate, snapshot, click, fill |
| `cmux-workspace` | Scope actions to the calling agent's workspace without stealing focus |
| `cmux-settings` | Read and write `cmux.json` via the helper script |
| `cmux-diagnostics` | Health check: CLI, socket, hooks, session restore, notifications |
| `cmux-keyboard-shortcuts` | Inspect and customize shortcuts |
| `cmux-markdown` | Render Markdown in a side pane |

Install all at once:
```bash
./skills.sh
# or remotely:
curl -fsSL https://raw.githubusercontent.com/manaflow-ai/cmux/main/skills.sh | bash
```

Sources: [skills.sh:1-30](skills.sh), [skills/cmux/skill.md](skills/cmux/skill.md), [skills/cmux-browser/skill.md](skills/cmux-browser/skill.md)

---

## What to Read Next

Your next step depends on what you want to build or change.

### Building an agent integration

1. **Start**: `skills/cmux/skill.md` — the handle model, core commands, and topology API
2. **Stay in scope**: `skills/cmux-workspace/skill.md` — non-disruptive automation, how to read `CMUX_WORKSPACE_ID` and `CMUX_SURFACE_ID`
3. **Browser automation**: `skills/cmux-browser/skill.md`
4. **Agent session resume**: `Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/AgentLaunchSanitizer.swift` — how launch arguments are sanitized per agent kind
5. **Hook injection**: `Packages/CMUXAgentLaunch/Sources/CMUXAgentLaunch/HermesAgentHookConfig.swift`
6. **Debugging**: `skills/cmux-diagnostics/skill.md` — socket health, CLI ping, hook validation

### Customizing the UI or adding settings

1. **Config file structure**: `Sources/CmuxConfig.swift` — the full parsed shape of `cmux.json`
2. **UI settings**: `Sources/CmuxConfigUI.swift`, `Sources/AppearanceSettings.swift`
3. **Sidebar row rendering**: `Sources/ExtensionSidebarWorkspaceRowView.swift` — the `Equatable` snapshot pattern required to avoid CPU spin loops
4. **Sidebar state**: `Sources/Sidebar/SidebarState.swift`
5. **Pitfalls**: Re-read the snapshot-boundary and no-state-mutation-in-body-computations rules in `CLAUDE.md` before touching any panel with a `LazyVStack` or `ForEach`

### Hacking on the terminal core

1. **Ghostty submodule**: `ghostty/` — the libghostty rendering engine; changes must be pushed to `manaflow-ai/ghostty` before updating the parent pointer
2. **Terminal surface views**: `Sources/GhosttyTerminalView.swift` — typing-latency-sensitive; `forceRefresh()` is called on every keystroke
3. **Socket commands**: `Sources/SocketControlSettings.swift` for access modes; `Sources/CmuxSocketEventMapper.swift` for event routing
4. **Debug log**: `tail -f "$(cat /tmp/cmux-last-debug-log-path)"` gives a live ring-buffer view of key, mouse, focus, and split events during a tagged Debug run

---

## One Rule to Carry Forward

The socket is the boundary where agents and the app meet. Everything on the agent side (skills, launch sanitizers, hook injectors) is designed to be additive and reversible — it injects, sanitizes, and cleans up without permanently altering the user's config. Everything on the app side (socket modes, threading policy, sidebar snapshots) is designed to let agents act without stealing focus or blocking the main thread. That contract is the reason cmux can run multiple agents in parallel workspaces without the UI freezing.

Sources: [Sources/SocketControlSettings.swift:44-54](Sources/SocketControlSettings.swift), [CLAUDE.md — Socket command threading policy and Socket focus policy](CLAUDE.md)