# manaflow-ai/cmux architecture

> Architecture diagram of the GitHub repository manaflow-ai/cmux, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/manaflow-ai/cmux
- Repository: https://github.com/manaflow-ai/cmux

## Overview

cmux is a native macOS terminal and browser for developers working with AI coding agents. The main workflow is to create and organize workspaces and split panes, run local or remote terminals, and receive agent notifications in the sidebar when attention is needed. The CLI and socket API automate those operations; browser panes support scripted interaction. The graph includes documented capabilities and indexed core modules, plus catalog-query relationships visible in excerpts. Several runtime modules are indexed but unsampled, so their internal call paths are not inferred.

Main entry points: [`Sources/Workspace.swift`](https://github.com/manaflow-ai/cmux/blob/main/Sources/Workspace.swift) (Workspace state), [`CLI/cmux.swift`](https://github.com/manaflow-ai/cmux/blob/main/CLI/cmux.swift) (CLI and socket API), [`Sources/Surfaces/SurfaceCatalog.swift`](https://github.com/manaflow-ai/cmux/blob/main/Sources/Surfaces/SurfaceCatalog.swift) (Surface catalog), [`Sources/Surfaces/SurfaceCatalogQueryService.swift`](https://github.com/manaflow-ai/cmux/blob/main/Sources/Surfaces/SurfaceCatalogQueryService.swift) (Catalog queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspaces and terminals"]
  node_workspace["Workspace state<br/>[Workspace.swift]"]
  node_terminal["Terminal runtime"]
  node_splits[("Split layout")]
  node_ssh["SSH sessions"]
  node_browser["In-app browser"]
end

subgraph group_agent["Agent notifications"]
  node_feed["Agent work feed"]
  node_journal["Notification reconciliation"]
  node_agentchat[("Agent sessions")]
end

subgraph group_surfaces["Surface catalog"]
  node_catalog[("Surface catalog")]
  node_provider["Surface providers"]
  node_catalogquery["Catalog queries"]
  node_currentwork["Current work query"]
  node_cloudcreation["Cloud workspace creation"]
end

subgraph group_control["Automation and control"]
  node_cli["CLI and socket API<br/>[cmux.swift]"]
  node_automation["Automation rules"]
  node_palette["Command palette"]
end

subgraph group_shared["Shared services"]
  node_eventbus["Event bus<br/>[CmuxEventBus.swift]"]
  node_diagnostics["Diagnostic logging"]
  node_connectivity["Peer connectivity"]
  node_trust["Transport trust"]
  node_machineid["Machine identity"]
end

node_developer(("Developer"))

node_developer -->|"creates and organizes"| node_workspace
node_developer -->|"runs commands"| node_terminal
node_developer -->|"scripts browser"| node_browser
node_developer -->|"controls app"| node_cli
node_workspace -->|"organizes panes"| node_splits
node_workspace -->|"hosts terminals"| node_terminal
node_workspace -->|"hosts browser pane"| node_browser
node_developer -->|"starts remote session"| node_ssh
node_terminal -->|"emits agent signals"| node_journal
node_cli -->|"sends notifications"| node_journal
node_journal -.->|"surfaces agent activity"| node_feed
node_cli -->|"controls workspaces"| node_workspace
node_cli -->|"controls browser"| node_browser
node_automation -->|"subscribes to events"| node_eventbus
node_catalogquery -->|"reads and refreshes"| node_catalog
node_catalog -->|"refreshes and materializes"| node_provider
node_cloudcreation -.->|"creates cloud workspaces"| node_catalog
node_currentwork -->|"captures catalog"| node_catalog
node_currentwork -->|"reads agent records"| node_agentchat
node_catalogquery -->|"resolves machine"| node_machineid
node_catalogquery -->|"resolves provider"| node_provider
node_developer -->|"searches commands"| node_palette
node_connectivity -.->|"uses trust broker"| node_trust

click node_workspace "https://github.com/manaflow-ai/cmux/blob/main/Sources/Workspace.swift"
click node_terminal "https://github.com/manaflow-ai/cmux/blob/main/Sources/TerminalController.swift"
click node_splits "https://github.com/manaflow-ai/cmux/blob/main/Sources/DockSplitStore.swift"
click node_ssh "https://github.com/manaflow-ai/cmux/blob/main/CLI/CMUXCLI%2BSSHTui.swift"
click node_browser "https://github.com/manaflow-ai/cmux/blob/main/CLI/CMUXCLI%2BBrowserRepl.swift"
click node_feed "https://github.com/manaflow-ai/cmux/blob/main/Sources/Feed/FeedCoordinator.swift"
click node_journal "https://github.com/manaflow-ai/cmux/blob/main/Packages/macOS/CmuxAgentJournal/Sources/CmuxAgentJournal/AgentNotificationReconciler.swift"
click node_agentchat "https://github.com/manaflow-ai/cmux/blob/main/Sources/Mobile/AgentChat/AgentChatSessionRegistry.swift"
click node_cli "https://github.com/manaflow-ai/cmux/blob/main/CLI/cmux.swift"
click node_automation "https://github.com/manaflow-ai/cmux/blob/main/Sources/AutomationEngine.swift"
click node_palette "https://github.com/manaflow-ai/cmux/blob/main/Packages/macOS/CmuxCommandPalette/Sources/CmuxCommandPalette/Search/CommandPaletteSearchEngine.swift"
click node_catalog "https://github.com/manaflow-ai/cmux/blob/main/Sources/Surfaces/SurfaceCatalog.swift"
click node_provider "https://github.com/manaflow-ai/cmux/blob/main/Sources/Surfaces/SurfaceProvider.swift"
click node_catalogquery "https://github.com/manaflow-ai/cmux/blob/main/Sources/Surfaces/SurfaceCatalogQueryService.swift"
click node_currentwork "https://github.com/manaflow-ai/cmux/blob/main/Sources/Surfaces/CurrentWorkQueryService.swift"
click node_cloudcreation "https://github.com/manaflow-ai/cmux/blob/main/Sources/Surfaces/CloudWorkspaceCreationCoordinator.swift"
click node_eventbus "https://github.com/manaflow-ai/cmux/blob/main/Sources/CmuxEventBus.swift"
click node_diagnostics "https://github.com/manaflow-ai/cmux/blob/main/Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/DiagnosticLog.swift"
click node_connectivity "https://github.com/manaflow-ai/cmux/blob/main/Packages/Shared/CmuxIrohTransport/Sources/CmuxIrohTransport/CmxConnectivityPeerSession.swift"
click node_trust "https://github.com/manaflow-ai/cmux/blob/main/Packages/Shared/CmuxIrohTransport/Sources/CmuxIrohTransport/CmxIrohTrustBrokerClient.swift"
click node_machineid "https://github.com/manaflow-ai/cmux/blob/main/Packages/macOS/CmuxSurfaceCatalogModel/Sources/CmuxSurfaceCatalogModel/SurfaceMachineID.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_workspace,node_terminal,node_splits,node_ssh,node_browser toneBlue
class node_feed,node_journal,node_agentchat toneAmber
class node_catalog,node_provider,node_catalogquery,node_currentwork,node_cloudcreation toneMint
class node_cli,node_automation,node_palette toneRose
class node_eventbus,node_diagnostics,node_connectivity,node_trust,node_machineid,node_developer toneIndigo
```

## Components

### Workspaces and terminals

- [Workspace state](https://github.com/manaflow-ai/cmux/blob/main/Sources/Workspace.swift): `Sources/Workspace.swift`
- [Terminal runtime](https://github.com/manaflow-ai/cmux/blob/main/Sources/TerminalController.swift): `Sources/TerminalController.swift`
- [Split layout](https://github.com/manaflow-ai/cmux/blob/main/Sources/DockSplitStore.swift): `Sources/DockSplitStore.swift`
- [SSH sessions](https://github.com/manaflow-ai/cmux/blob/main/CLI/CMUXCLI%2BSSHTui.swift): `CLI/CMUXCLI+SSHTui.swift`
- [In-app browser](https://github.com/manaflow-ai/cmux/blob/main/CLI/CMUXCLI%2BBrowserRepl.swift): `CLI/CMUXCLI+BrowserRepl.swift`

### Agent notifications

- [Agent work feed](https://github.com/manaflow-ai/cmux/blob/main/Sources/Feed/FeedCoordinator.swift): `Sources/Feed/FeedCoordinator.swift`
- [Notification reconciliation](https://github.com/manaflow-ai/cmux/blob/main/Packages/macOS/CmuxAgentJournal/Sources/CmuxAgentJournal/AgentNotificationReconciler.swift): `Packages/macOS/CmuxAgentJournal/Sources/CmuxAgentJournal/AgentNotificationReconciler.swift`
- [Agent sessions](https://github.com/manaflow-ai/cmux/blob/main/Sources/Mobile/AgentChat/AgentChatSessionRegistry.swift): `Sources/Mobile/AgentChat/AgentChatSessionRegistry.swift`

### Surface catalog

- [Surface catalog](https://github.com/manaflow-ai/cmux/blob/main/Sources/Surfaces/SurfaceCatalog.swift): `Sources/Surfaces/SurfaceCatalog.swift`
- [Surface providers](https://github.com/manaflow-ai/cmux/blob/main/Sources/Surfaces/SurfaceProvider.swift): `Sources/Surfaces/SurfaceProvider.swift`
- [Catalog queries](https://github.com/manaflow-ai/cmux/blob/main/Sources/Surfaces/SurfaceCatalogQueryService.swift): `Sources/Surfaces/SurfaceCatalogQueryService.swift`
- [Current work query](https://github.com/manaflow-ai/cmux/blob/main/Sources/Surfaces/CurrentWorkQueryService.swift): `Sources/Surfaces/CurrentWorkQueryService.swift`
- [Cloud workspace creation](https://github.com/manaflow-ai/cmux/blob/main/Sources/Surfaces/CloudWorkspaceCreationCoordinator.swift): `Sources/Surfaces/CloudWorkspaceCreationCoordinator.swift`

### Automation and control

- [CLI and socket API](https://github.com/manaflow-ai/cmux/blob/main/CLI/cmux.swift): `CLI/cmux.swift`
- [Automation rules](https://github.com/manaflow-ai/cmux/blob/main/Sources/AutomationEngine.swift): `Sources/AutomationEngine.swift`
- [Command palette](https://github.com/manaflow-ai/cmux/blob/main/Packages/macOS/CmuxCommandPalette/Sources/CmuxCommandPalette/Search/CommandPaletteSearchEngine.swift): `Packages/macOS/CmuxCommandPalette/Sources/CmuxCommandPalette/Search/CommandPaletteSearchEngine.swift`

### Shared services

- [Event bus](https://github.com/manaflow-ai/cmux/blob/main/Sources/CmuxEventBus.swift): `Sources/CmuxEventBus.swift`
- [Diagnostic logging](https://github.com/manaflow-ai/cmux/blob/main/Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/DiagnosticLog.swift): `Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/DiagnosticLog.swift`
- [Peer connectivity](https://github.com/manaflow-ai/cmux/blob/main/Packages/Shared/CmuxIrohTransport/Sources/CmuxIrohTransport/CmxConnectivityPeerSession.swift): `Packages/Shared/CmuxIrohTransport/Sources/CmuxIrohTransport/CmxConnectivityPeerSession.swift`
- [Transport trust](https://github.com/manaflow-ai/cmux/blob/main/Packages/Shared/CmuxIrohTransport/Sources/CmuxIrohTransport/CmxIrohTrustBrokerClient.swift): `Packages/Shared/CmuxIrohTransport/Sources/CmuxIrohTransport/CmxIrohTrustBrokerClient.swift`
- [Machine identity](https://github.com/manaflow-ai/cmux/blob/main/Packages/macOS/CmuxSurfaceCatalogModel/Sources/CmuxSurfaceCatalogModel/SurfaceMachineID.swift): `Packages/macOS/CmuxSurfaceCatalogModel/Sources/CmuxSurfaceCatalogModel/SurfaceMachineID.swift`

### Other components

- **Developer**

## Connections

- Developer → Workspace state: creates and organizes (evidence: `README.md`)
- Developer → Terminal runtime: runs commands (evidence: `README.md`)
- Developer → In-app browser: scripts browser (evidence: `README.md`)
- Developer → CLI and socket API: controls app (evidence: `README.md`)
- Workspace state → Split layout: organizes panes (evidence: `README.md`)
- Workspace state → Terminal runtime: hosts terminals (evidence: `README.md`)
- Workspace state → In-app browser: hosts browser pane (evidence: `README.md`)
- Developer → SSH sessions: starts remote session (evidence: `README.md`)
- Terminal runtime → Notification reconciliation: emits agent signals (evidence: `README.md`)
- CLI and socket API → Notification reconciliation: sends notifications (evidence: `README.md`)
- Notification reconciliation → Agent work feed: surfaces agent activity
- CLI and socket API → Workspace state: controls workspaces (evidence: `README.md`)
- CLI and socket API → In-app browser: controls browser (evidence: `README.md`)
- Automation rules → Event bus: subscribes to events (evidence: `Sources/AutomationEngine.swift`)
- Catalog queries → Surface catalog: reads and refreshes (evidence: `Sources/Surfaces/SurfaceCatalogQueryService.swift`)
- Surface catalog → Surface providers: refreshes and materializes (evidence: `Sources/Surfaces/SurfaceCatalog.swift`)
- Cloud workspace creation → Surface catalog: creates cloud workspaces (evidence: `Sources/Surfaces/SurfaceCatalog.swift`)
- Current work query → Surface catalog: captures catalog (evidence: `Sources/Surfaces/CurrentWorkQueryService.swift`)
- Current work query → Agent sessions: reads agent records (evidence: `Sources/Surfaces/CurrentWorkQueryService.swift`)
- Catalog queries → Machine identity: resolves machine (evidence: `Sources/Surfaces/SurfaceCatalogQueryService.swift`)
- Catalog queries → Surface providers: resolves provider (evidence: `Sources/Surfaces/SurfaceCatalogQueryService.swift`)
- Developer → Command palette: searches commands (evidence: `README.md`)
- Peer connectivity → Transport trust: uses trust broker
