How cai0baa/cmux-for-linux works
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: AppShell.tsx AppShell · workspaceStore.ts Zustand stores · mod.rs Commands · TerminalPane.tsx Terminal pane
Components 20
Frontend
React + TypeScript UI shell, workspace views, and client-side state
- App shell · Root UI composition and startup wiring
src/App.tsx - AppShell · Top-level chrome and modal orchestration
src/components/layout/AppShell.tsx - Title Bar · Native-style window controls and status area
src/components/layout/TitleBar.tsx - Tab bar · Workspace switching and tab presentation
src/components/layout/TabBar.tsx - Workspace view · Main workspace area for pane layout and focus management
src/components/workspace/WorkspaceView.tsx - Terminal grid · Split layout and pane arrangement engine
src/components/workspace/TerminalGrid.tsx - Terminal pane · Single terminal pane container with metadata and controls
src/components/workspace/TerminalPane.tsx - XTerm wrapper · Frontend terminal rendering and input capture
src/components/terminal/XTermWrapper.tsx - Browser pane · Embedded browser workspace surface
src/components/browser/BrowserPane.tsx - Command palette · Keyboard-driven command and search surface
src/components/layout/CommandPalette.tsx - Socket listener · Consumes backend push events into UI state
src/components/layout/SocketListener.tsx - Zustand stores · Workspace, terminal, UI, theme, browser, and keybinding state
src/stores/workspaceStore.ts - Persist hook · Loads and saves workspace state across launches
src/hooks/useWorkspacePersist.ts - IPC client · 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 · Session-oriented terminal process layer
src-tauri/src/pty/session.rs - PTY manager · Creates, tracks, and coordinates terminal sessions
src-tauri/src/pty/manager.rs - Runtime events · Emits async backend updates to the frontend
src-tauri/src/events.rs - Commands · Tauri command entry points for workspace, terminal, window, and browser actions
src-tauri/src/commands/mod.rs - Storage · Native database and workspace persistence backend
src-tauri/src/db/storage.rs
Platform Integrations
OS-specific browser hooks and packaging boundary
- Browser native · Platform-specific browser integration behind a common interface
src-tauri/src/browser/mod.rs
Connections 23
- 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