93 lines
4.2 KiB
Text
93 lines
4.2 KiB
Text
---
|
|
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) |
|