Concepts

cmux organizes your terminals in a four-level hierarchy. Understanding these levels helps when using the socket API, CLI, and keyboard shortcuts.

Hierarchy

Window
  └── Workspace (sidebar entry)
        └── Pane (split region)
              └── Surface (tab within pane)
                    └── Panel (terminal or browser content)

Window

A macOS window. Open multiple windows with ⌘⇧N. Each window has its own sidebar with independent workspaces.

Workspace

A sidebar entry. Each workspace contains one or more split panes. Workspaces are what you see listed in the left sidebar.

In the UI and keyboard shortcuts, workspaces are often called “tabs” since they behave like tabs in the sidebar. The socket API and environment variables use the term “workspace”.

Shortcuts: ⌘N (new), ⌘1–⌘9 (jump), ⌘⇧W (close), ⌘⇧[ / ⌘⇧] (prev/next)

Pane

A split region within a workspace. Created by splitting with ⌘D (right) or ⌘⇧D (down). Navigate between panes with ⌥⌘ + arrow keys.

Each pane can hold multiple surfaces (tabs within the pane).

Surface

A tab within a pane. Each pane has its own tab bar and can hold multiple surfaces. Created with ⌘T, navigated with ⌘[ / ⌘] or ⌃1–⌃9.

Surfaces are the individual terminal or browser sessions you interact with. Each surface has its own CMUX_SURFACE_ID environment variable.

Panel

The content inside a surface. Currently two types:

• Terminal — a Ghostty terminal session
• Browser — an embedded web view

Panel is mostly an internal concept. In the socket API and CLI, you interact with surfaces rather than panels directly.

Visual example

┌──────────────────────────────────────────────────────┐
│ ┌──────────┐ ┌─────────────────────────────────────┐ │
│ │ Sidebar  │ │ Workspace "dev"                     │ │
│ │          │ │                                     │ │
│ │          │ │ ┌───────────────┬─────────────────┐ │ │
│ │ > dev    │ │ │ Pane 1        │ Pane 2          │ │ │
│ │   server │ │ │ [S1] [S2]     │ [S1]            │ │ │
│ │   logs   │ │ │               │                 │ │ │
│ │          │ │ │  Terminal     │  Terminal       │ │ │
│ │          │ │ │               │                 │ │ │
│ │          │ │ └───────────────┴─────────────────┘ │ │
│ └──────────┘ └─────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘

In this example:

• The window contains a sidebar with three workspaces (dev, server, logs)
• Workspace “dev” is selected, showing two panes side by side
• Pane 1 has two surfaces ([S1] and [S2] in the tab bar), with S1 active
• Pane 2 has one surface
• Each surface contains a panel (a terminal in this case)

Summary