# cai0baa/cmux-for-linux architecture

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

- Interactive diagram: https://gitdiagram.com/cai0baa/cmux-for-linux
- Repository: https://github.com/cai0baa/cmux-for-linux

## Overview

1. **Overall shape**
   ptrcode is a desktop app, not a web app: a **Tauri v2 Rust backend** hosts native capabilities, while a **React + TypeScript + Vite frontend** renders the UI. The app is built around a terminal-workspace model with multiple panes, workspaces, and a command palette.

2. **Primary runtime boundary**
   The architectural boundary is between the **frontend process** in `src/` and the **native backend** in `src-tauri/`. The frontend drives user interaction; the Rust side owns OS-facing work such as PTYs, window actions, persistence, and platform-specific browser integration.

3. **Frontend shell and composition**
   The top-level UI starts in `src/App.tsx` and is assembled through `AppShell`, `TitleBar`, `TabBar`, `WorkspaceView`, and ancillary overlays like `CommandPalette`, `NotificationPanel`, and `KeybindingsModal`. This is a keyboard-first shell that coordinates panes, tabs, and modal surfaces rather than a traditional page hierarchy.

4. **Workspace and pane model**
   The main workspace area is organized in `src/components/workspace/` around `WorkspaceView`, `TerminalGrid`, `TerminalPane`, and pane/tab headers. The UI supports split layouts, per-workspace state, pane focus navigation, zooming, and pane-level metadata. This is the core visual hierarchy to reflect in an architecture diagram.

5. **Terminal subsystem**
   Terminal rendering is handled by **xterm.js** through `XTermWrapper`. The frontend renders terminal instances, but the actual shell processes live in the Rust PTY layer. User keystrokes and terminal output therefore flow across the Tauri IPC boundary between xterm in the UI and PTY sessions in the backend.

6. **Rust PTY and session management**
   The backend terminal stack is split into `pty/session.rs`, `pty/manager.rs`, and `pty/monitor.rs`. This suggests a session-oriented design where the manager creates and tracks terminal sessions, the session layer represents individual PTYs, and the monitor watches lifecycle/state changes. This subsystem is the source of terminal I/O events for the UI.

7. **Persistence and workspace state**
   Persistent application state is a major subsystem in `src/stores/` and `src/hooks/useWorkspacePersist.ts`, backed by Rust database/storage code in `src-tauri/src/db/`. Workspaces, layouts, pane metadata, theme, browser state, and keybindings are represented in frontend stores and saved/restored across launches via backend storage.

8. **IPC and command surface**
   The frontend talks to Tauri through `src/lib/ipc.ts`, while the backend exposes commands grouped under `src-tauri/src/commands/` for `terminal`, `workspace`, `window`, and `browser`. These commands are the explicit control plane for creation, focus, splitting, closing, navigation, and other app actions.

9. **Event-driven UI updates**
   The backend emits runtime changes through `src-tauri/src/events.rs`, and the frontend consumes them through components such as `SocketListener` plus the Zustand stores. This indicates a push-based update path for terminal output, notifications, workspace changes, and other async state rather than purely polling-based synchronization.

10. **Browser and platform-specific capabilities**
   There is a separate browser subsystem with a frontend `BrowserPane` and backend `browser/` modules for `linux`, `macos`, and `windows`. That split implies platform-specific behavior is isolated behind a common interface, which is important for any diagram showing cross-platform capabilities and conditional native integrations.

11. **UI state and interaction model**
   Most interactive state lives in Zustand stores: `uiStore`, `workspaceStore`, `workspaceLayoutStore`, `workspaceListStore`, `terminalStore`, `browserStore`, `themeStore`, and `keybindingStore`. This means the frontend architecture is store-driven, with components mostly subscribing to state rather than owning business logic locally.

12. **Setup, theming, and shared UI systems**
   The app also includes a setup flow (`src/components/setup/`) for initial workspace/agent configuration, plus theme infrastructure (`ThemeSwitcher`, `themeDefinitions`, design tokens in `docs/design/`). Common layout behavior, error boundaries, and keyboard help are all part of the reusable shell layer, not isolated feature pages.

13. **Cross-platform packaging and release**
   Build and release are handled through Tauri and GitHub Actions (`.github/workflows/release.yml`), producing desktop artifacts for Linux, macOS, and Windows. The repo structure and docs show a packaging-oriented architecture where platform output is part of the product boundary, not an afterthought.

14. **Planned expansion area**
   The docs describe upcoming multi-agent coordination and swarm workflows as a differentiator. In the current architecture, that future capability would likely extend the existing command/event/state model rather than replacing it, using the same Tauri IPC, persistence, and workspace shell foundations.

Main entry points: [`src/components/layout/AppShell.tsx`](https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/layout/AppShell.tsx) (AppShell), [`src/stores/workspaceStore.ts`](https://github.com/cai0baa/cmux-for-linux/blob/master/src/stores/workspaceStore.ts) (Zustand stores), [`src-tauri/src/commands/mod.rs`](https://github.com/cai0baa/cmux-for-linux/blob/master/src-tauri/src/commands/mod.rs) (Commands), [`src/components/workspace/TerminalPane.tsx`](https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/workspace/TerminalPane.tsx) (Terminal pane)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app["App shell<br/>React entry<br/>[App.tsx]"]
  node_shell["AppShell<br/>Layout shell<br/>[AppShell.tsx]"]
  node_titlebar["Title Bar<br/>Window chrome<br/>[TitleBar.tsx]"]
  node_tabs["Tab bar<br/>Workspace tabs<br/>[TabBar.tsx]"]
  node_workspace["Workspace view<br/>Workspace UI<br/>[WorkspaceView.tsx]"]
  node_grid["Terminal grid<br/>Pane layout<br/>[TerminalGrid.tsx]"]
  node_pane["Terminal pane<br/>Pane view<br/>[TerminalPane.tsx]"]
  node_xterm["XTerm wrapper<br/>Terminal renderer<br/>[XTermWrapper.tsx]"]
  node_browserpane["Browser pane<br/>Browser UI<br/>[BrowserPane.tsx]"]
  node_palette["Command palette<br/>Overlay<br/>[CommandPalette.tsx]"]
  node_listener["Socket listener<br/>Event bridge<br/>[SocketListener.tsx]"]
  node_stores["Zustand stores<br/>Client state<br/>[workspaceStore.ts]"]
  node_persist["Persist hook<br/>State sync"]
  node_ipc["IPC client<br/>Tauri bridge<br/>[ipc.ts]"]
end

subgraph group_backend["Native Backend"]
  node_pty[("PTY sessions<br/>Terminal backend<br/>[session.rs]")]
  node_ptymgr["PTY manager<br/>Session manager<br/>[manager.rs]"]
  node_events(("Runtime events<br/>Event bus<br/>[events.rs]"))
  node_commands["Commands<br/>Control plane<br/>[mod.rs]"]
  node_storage[("Storage<br/>Persistence layer<br/>[storage.rs]")]
end

subgraph group_platform["Platform Integrations"]
  node_browser["Browser native<br/>Platform browser<br/>[mod.rs]"]
end

node_app -->|"composes"| node_shell
node_shell -->|"includes"| node_titlebar
node_shell -->|"includes"| node_tabs
node_shell -->|"hosts"| node_workspace
node_shell -->|"overlays"| node_palette
node_workspace -->|"lays out"| node_grid
node_grid -->|"contains"| node_pane
node_pane -->|"renders"| node_xterm
node_pane -->|"alternates"| node_browserpane
node_xterm -->|"sends input"| node_ipc
node_ipc -->|"invokes"| node_commands
node_commands -->|"controls"| node_ptymgr
node_ptymgr -->|"owns"| node_pty
node_pty -->|"emits"| node_events
node_events -->|"pushes"| node_listener
node_listener -->|"updates"| node_stores
node_stores -->|"drives"| node_workspace
node_stores -->|"feeds"| node_xterm
node_stores -->|"feeds"| node_browserpane
node_persist -->|"syncs"| node_stores
node_commands -->|"persists"| node_storage
node_storage -->|"loads"| node_persist
node_commands -->|"opens"| node_browser

click node_app "https://github.com/cai0baa/cmux-for-linux/blob/master/src/App.tsx"
click node_shell "https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/layout/AppShell.tsx"
click node_titlebar "https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/layout/TitleBar.tsx"
click node_tabs "https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/layout/TabBar.tsx"
click node_workspace "https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/workspace/WorkspaceView.tsx"
click node_grid "https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/workspace/TerminalGrid.tsx"
click node_pane "https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/workspace/TerminalPane.tsx"
click node_xterm "https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/terminal/XTermWrapper.tsx"
click node_browserpane "https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/browser/BrowserPane.tsx"
click node_palette "https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/layout/CommandPalette.tsx"
click node_listener "https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/layout/SocketListener.tsx"
click node_stores "https://github.com/cai0baa/cmux-for-linux/blob/master/src/stores/workspaceStore.ts"
click node_persist "https://github.com/cai0baa/cmux-for-linux/blob/master/src/hooks/useWorkspacePersist.ts"
click node_ipc "https://github.com/cai0baa/cmux-for-linux/blob/master/src/lib/ipc.ts"
click node_pty "https://github.com/cai0baa/cmux-for-linux/blob/master/src-tauri/src/pty/session.rs"
click node_ptymgr "https://github.com/cai0baa/cmux-for-linux/blob/master/src-tauri/src/pty/manager.rs"
click node_events "https://github.com/cai0baa/cmux-for-linux/blob/master/src-tauri/src/events.rs"
click node_commands "https://github.com/cai0baa/cmux-for-linux/blob/master/src-tauri/src/commands/mod.rs"
click node_storage "https://github.com/cai0baa/cmux-for-linux/blob/master/src-tauri/src/db/storage.rs"
click node_browser "https://github.com/cai0baa/cmux-for-linux/blob/master/src-tauri/src/browser/mod.rs"

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_app,node_shell,node_titlebar,node_tabs,node_workspace,node_grid,node_pane,node_xterm,node_browserpane,node_palette,node_listener,node_stores,node_persist,node_ipc toneBlue
class node_pty,node_ptymgr,node_events,node_commands,node_storage toneAmber
class node_browser toneMint
```

## Components

### Frontend

React + TypeScript UI shell, workspace views, and client-side state

- [App shell](https://github.com/cai0baa/cmux-for-linux/blob/master/src/App.tsx): React entry · Root UI composition and startup wiring · `src/App.tsx`
- [AppShell](https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/layout/AppShell.tsx): Layout shell · Top-level chrome and modal orchestration · `src/components/layout/AppShell.tsx`
- [Title Bar](https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/layout/TitleBar.tsx): Window chrome · Native-style window controls and status area · `src/components/layout/TitleBar.tsx`
- [Tab bar](https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/layout/TabBar.tsx): Workspace tabs · Workspace switching and tab presentation · `src/components/layout/TabBar.tsx`
- [Workspace view](https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/workspace/WorkspaceView.tsx): Workspace UI · Main workspace area for pane layout and focus management · `src/components/workspace/WorkspaceView.tsx`
- [Terminal grid](https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/workspace/TerminalGrid.tsx): Pane layout · Split layout and pane arrangement engine · `src/components/workspace/TerminalGrid.tsx`
- [Terminal pane](https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/workspace/TerminalPane.tsx): Pane view · Single terminal pane container with metadata and controls · `src/components/workspace/TerminalPane.tsx`
- [XTerm wrapper](https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/terminal/XTermWrapper.tsx): Terminal renderer · Frontend terminal rendering and input capture · `src/components/terminal/XTermWrapper.tsx`
- [Browser pane](https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/browser/BrowserPane.tsx): Browser UI · Embedded browser workspace surface · `src/components/browser/BrowserPane.tsx`
- [Command palette](https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/layout/CommandPalette.tsx): Overlay · Keyboard-driven command and search surface · `src/components/layout/CommandPalette.tsx`
- [Socket listener](https://github.com/cai0baa/cmux-for-linux/blob/master/src/components/layout/SocketListener.tsx): Event bridge · Consumes backend push events into UI state · `src/components/layout/SocketListener.tsx`
- [Zustand stores](https://github.com/cai0baa/cmux-for-linux/blob/master/src/stores/workspaceStore.ts): Client state · Workspace, terminal, UI, theme, browser, and keybinding state · `src/stores/workspaceStore.ts`
- [Persist hook](https://github.com/cai0baa/cmux-for-linux/blob/master/src/hooks/useWorkspacePersist.ts): State sync · Loads and saves workspace state across launches · `src/hooks/useWorkspacePersist.ts`
- [IPC client](https://github.com/cai0baa/cmux-for-linux/blob/master/src/lib/ipc.ts): Tauri bridge · Frontend command surface for native capabilities · `src/lib/ipc.ts`

### Native Backend

Tauri v2 Rust runtime for PTYs, commands, events, storage, and platform integrations

- [PTY sessions](https://github.com/cai0baa/cmux-for-linux/blob/master/src-tauri/src/pty/session.rs): Terminal backend · Session-oriented terminal process layer · `src-tauri/src/pty/session.rs`
- [PTY manager](https://github.com/cai0baa/cmux-for-linux/blob/master/src-tauri/src/pty/manager.rs): Session manager · Creates, tracks, and coordinates terminal sessions · `src-tauri/src/pty/manager.rs`
- [Runtime events](https://github.com/cai0baa/cmux-for-linux/blob/master/src-tauri/src/events.rs): Event bus · Emits async backend updates to the frontend · `src-tauri/src/events.rs`
- [Commands](https://github.com/cai0baa/cmux-for-linux/blob/master/src-tauri/src/commands/mod.rs): Control plane · Tauri command entry points for workspace, terminal, window, and browser actions · `src-tauri/src/commands/mod.rs`
- [Storage](https://github.com/cai0baa/cmux-for-linux/blob/master/src-tauri/src/db/storage.rs): Persistence layer · Native database and workspace persistence backend · `src-tauri/src/db/storage.rs`

### Platform Integrations

OS-specific browser hooks and packaging boundary

- [Browser native](https://github.com/cai0baa/cmux-for-linux/blob/master/src-tauri/src/browser/mod.rs): Platform browser · Platform-specific browser integration behind a common interface · `src-tauri/src/browser/mod.rs`

## Connections

- App shell → AppShell: composes · Root app builds the shell and global overlays
- AppShell → Title Bar: includes · Shell renders window chrome
- AppShell → Tab bar: includes · Shell renders workspace tabs
- AppShell → Workspace view: hosts · Shell hosts the main workspace surface
- AppShell → Command palette: overlays · Shell can present command palette and modals
- Workspace view → Terminal grid: lays out · Workspace view delegates split layout to the grid
- Terminal grid → Terminal pane: contains · Grid organizes individual terminal panes
- Terminal pane → XTerm wrapper: renders · Each pane wraps an xterm instance
- Terminal pane → Browser pane: alternates · Workspace can show browser panes alongside terminals
- XTerm wrapper → IPC client: sends input · Keystrokes and terminal actions cross into native commands
- IPC client → Commands: invokes · Frontend issues native actions through Tauri commands
- Commands → PTY manager: controls · Terminal commands create and manage sessions
- PTY manager → PTY sessions: owns · Manager tracks individual PTY sessions
- PTY sessions → Runtime events: emits · PTY lifecycle and output feed runtime events
- Runtime events → Socket listener: pushes · Frontend listener receives native events
- Socket listener → Zustand stores: updates · Events hydrate and mutate client state
- Zustand stores → Workspace view: drives · Workspace state determines layout and focus
- Zustand stores → XTerm wrapper: feeds · Terminal state and instances are reflected in the renderer
- Zustand stores → Browser pane: feeds · Browser state controls the browser pane UI
- Persist hook → Zustand stores: syncs · Persistence hook restores and saves store state
- Commands → Storage: persists · Commands read and write durable workspace data
- Storage → Persist hook: loads · Saved workspace state is restored at startup
- Commands → Browser native: opens · Browser commands route to native platform integration
