---
title: Concepts
description: Understanding cmux's window, workspace, pane, and surface hierarchy
---

# 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. You can 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".

| Context | Term Used |
|---------|-----------|
| Sidebar UI | Tab |
| Keyboard shortcuts | Workspace or tab |
| Socket API | `workspace` |
| Environment variable | `CMUX_WORKSPACE_ID` |

**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 Table

| Level | What It Is | Created By | Identified By |
|-------|-----------|------------|---------------|
| Window | macOS window | **⌘⇧N** | -- |
| Workspace | Sidebar entry | **⌘N** | `CMUX_WORKSPACE_ID` |
| Pane | Split region | **⌘D** / **⌘⇧D** | Pane ID (socket API) |
| Surface | Tab within pane | **⌘T** | `CMUX_SURFACE_ID` |
| Panel | Terminal or browser | Automatic | Panel ID (internal) |
