Workspace・Pane・Surface：CMUXの3層構造を理解する

多くの人はCMUXをインストールし、開いて「tmuxとそんなに変わらないな」と思い — 結局機能の30%しか使わない。問題はほぼ常に同じだ：3層構造を内面化していない。理解すれば、全ての設計判断が意味をなし始め、タスクごとに画面スペースを実際に分割できるようになる。

まず視覚的な概観から

CMUXのインターフェースはこのような形をしている：

┌──────────────────────────────────────────────────────┐
│ ┌──────────┐ ┌─────────────────────────────────────┐ │
│ │ サイドバー│ │ Workspace "dev"                     │ │
│ │          │ │                                     │ │
│ │          │ │ ┌───────────────┬─────────────────┐ │ │
│ │ > dev    │ │ │ Pane 1        │ Pane 2          │ │ │
│ │   server │ │ │ [S1] [S2]     │ [S1]            │ │ │
│ │   logs   │ │ │               │                 │ │ │
│ │          │ │ │  ターミナル   │  ターミナル     │ │ │
│ │          │ │ │               │                 │ │ │
│ └──────────┘ └───────────────┴─────────────────┘ │ │
└──────────────────────────────────────────────────────┘

左のサイドバーに3つのworkspace（dev、server、logs）がリスト表示されている。「dev」が現在選択されており、右側に2つの横並びのペインが表示され、Pane 1には2つのsurface（S1とS2）が含まれている。

これが3層だ：Workspace → Pane → Surface、そして下部のPanel。

レイヤー1：Window

最外層はmacOSウィンドウで、⌘⇧Nで作成する。実際にはこのレイヤーを管理することはほとんどない — 複数ウィンドウが必要になるのは、十分なモニタースペースがある場合だけだ。

レイヤー2：Workspace

WorkspaceはサイドバーのアイテムでI、⌘Nで作成する。

このレイヤーがタスクの整理方法だ — 1エージェント、1フィーチャーブランチ、1タスクがそれぞれ独自のworkspaceを持つ。各workspaceには固有の名前があり、色付けができ、CMUX_WORKSPACE_IDという環境変数を公開するのでスクリプトがどのworkspaceで実行されているかを把握できる。

実際の使用例：

feature-auth：認証機能開発、エージェントがここで実行される
test-runner：テスト実行専用のworkspace
logs：ログ監視、常時実行したまま

3つは完全に独立していて、サイドバーでステータスを一目でスキャンできる。

レイヤー3：Pane

Workspace内で、⌘D（水平）または⌘⇧D（垂直）を使って複数のペインに分割できる。

ペインは画面スペースの割り当て単位で、同じタスク内で複数の出力を同時に見ることができる。例えば：左にエージェントの出力、右にブラウザプレビュー — 同じ「タスク」の一部だが、両方を同時に見る必要がある。

レイヤー4：Surface

各ペインは複数のSurfaceを含めることができる — ブラウザのタブに似ており、⌘Tで作成する。各Surfaceには固有の識別子（CMUX_SURFACE_ID）があり、ソケットAPIで自動化する際に使用する。

Panel

下部レイヤー。各Surfaceが1つのPanelを実行し、ターミナルまたはブラウザのどちらかになれる。そう — Chromeに切り替えて戻ることなく、ペイン内で直接ブラウザを開けるのだ。

レイヤーサマリー

レイヤー	説明	作成	識別子
Window	macOSウィンドウ	`⌘⇧N`	—
Workspace	サイドバーのアイテム	`⌘N`	`CMUX_WORKSPACE_ID`
Pane	分割領域	`⌘D` / `⌘⇧D`	Pane ID（ソケットAPI）
Surface	ペイン内のタブ	`⌘T`	`CMUX_SURFACE_ID`
Panel	ターミナルまたはブラウザ	自動	Panel ID（内部）

この構造を使って複数エージェントを管理する方法

一般的な設定：

Workspace = エージェント（またはタスク）
エージェントごとに1つのworkspaceを作り、何をしているかで名前をつける — claude-feature、claude-test、monitoring。

Pane = 同じタスク内の異なる視点
フィーチャーworkspace内で、左にエージェントの出力、右にブラウザプレビュー — どちらもこのタスクに属するが、同時に見る必要がある。

Surface = スペースの確保
ペインに予備のシェルSurfaceを残しておくと、メインエージェントの出力を妨げることなく、いつでも手動で操作できる。

このレイアウトで画面が整理される — 各ペインに役割があり、どこを見ればいいか常にわかる。

3層構造はカバーした。次の記事：設定の調整 — フォント、カラー、スクロールバック、CMUXを使いやすくするその他の詳細：CMUX設定完全ガイド。