cmux 初心者向けユーザーズマニュアル — 並列AIエージェントを一望する完全ガイド

cmux とは

ひとことで言うと、「複数の AI エージェントを並列で走らせるための司令塔ターミナル」です。普通のターミナルを置き換えて、そのまま使えます。

🔰

初心者向け：「エージェント」とは claude や codex のように、ターミナルから指示するとコードを書いたり調べたりしてくれる AI のことです。cmux はそれらを同時に何体も動かし、状態を一画面で見えるようにします。

Ghostty（libghostty・GPU 加速）製のネイティブ macOS ターミナル。Swift / AppKit で書かれ、Electron を使っていません。だから起動が速く・メモリ消費が低い。
14 種類以上の AI エージェントがそのまま動く。Claude Code / Codex / Gemini CLI / OpenCode / Aider / Goose / Amp / Cline / Cursor Agent / Kiro / Copilot / Factory / Qoder / Rovo Dev など。ターミナルで動くものは基本すべて対応。
「誰が・どの状態か」が一目で分かる。左のサイドバーと青い「通知リング」で、待っているエージェントを見落としません。
内蔵のスクリプタブルブラウザ（Playwright 相当）。エージェントが自分で画面を操作して、UI の動作確認までできます。

🧩cmux が解決する「あるある」

複数のエージェントを普通のターミナルで回すと、こんな困りごとが起きます。

通知が全部「入力待ちです」で、どのエージェントが呼んでいるのか分からない。
タブ名が混ざって、どれがどの作業か見失う。
状態を知るにはペインを 1 つずつ覗くしかない。

cmux は、青い通知リング＋縦サイドバーで「誰が・どの状態か」を常時可視化することで、この 3 つをまとめて解決します。

なぜ cmux が優れているのか

「1 エージェント＝1 ウィンドウ」をやめるだけで、待ち時間と切り替えコストが消えます。数字でも裏付けがあります。

0

GitHub Stars ★

0

そのまま動くエージェント

0

リリース回数（活発）

0

導入コスト（無料OSS）

実績ある OSS。21.5k★を獲得し、Nvidia / Google / OpenAI の開発者にも使われています。ライセンスは GPL-3.0-or-later（個人・社内利用は無料。組織向けの商用ライセンスは別途）。
設定ほぼゼロ。既存の Ghostty 設定（~/.config/ghostty/config）を継承するので、テーマ・フォント・配色をそのまま引き継ぎます。
サブエージェント協調をネイティブ対応する唯一のターミナル。socket API でエージェント同士・自動化スクリプトと連携できます。

普通のターミナル vs cmux

ハンドルを左右にドラッグして見比べてください。左はウィンドウが散らかった普通のターミナル、右は cmux の整然としたサイドバーです。

➜ claude …
⎿ 入力待ち？

➜ codex …
⚠ どれが呼んでる？

➜ gemini …

➜ aider …
… どこ？

ウィンドウが散乱・状態が見えない

claude

codex

gemini

aider

➜ claude "refactor auth"
✓ 24/24 tests pass
● PR #412 を作成中…

● codex があなた待ち · ⌘⇧U

普通のターミナル

cmux

⇆

他ツールとの比較（正直版）

cmux の良いところだけでなく、弱点も正直に書きます。適材適所で使い分けるのが一番です。

観点	cmux	tmux	Warp	iTerm2
どのエージェントが待っているか可視化（通知リング）	◎	手動	○	×
内蔵スクリプタブルブラウザ（Playwright 相当）	◎	ほぼ無し	ほぼ無し	ほぼ無し
socket API でサブエージェント協調	◎ ネイティブ	×	×	×
設定の継承（ゼロ設定）	◎ Ghostty継承	手動	○	○
SSH 常駐・detach / reattach	× 非対応	◎ 得意	×	×
対応 OS	macOS 専用	クロス	クロス	macOS

⚠️

弱点：cmux は macOS 専用で、tmux のような detach・reattach（SSH 接続を切っても裏で走り続ける常駐）はありません。リモートに常駐させたい場合は cmux ssh ＋ tmux 併用が有効です。

インストール

macOS なら Homebrew で一発。3 ステップで完了します。

インストール

Homebrew の Cask を入れるだけ。公式サイトの DMG（Sparkle で自動更新）でも OK。

$ brew tap manaflow-ai/cmux
$ brew install --cask cmux

起動して設定を継承

初回起動で ~/.config/ghostty/config を自動読み込み。テーマ・フォント・配色がそのまま反映されます。

# 設定不要。開けば見慣れた配色に

通知フックを有効化

これで入力待ち・完了時に通知リングが光り、対応エージェントの resume 連携も入ります。

$ cmux hooks setup

💡

ヒント：更新は brew upgrade --cask cmux。DMG で入れた場合は Sparkle が自動でアップデートを案内してくれます。

🔰

初心者向け：Homebrew（brew）は macOS の定番パッケージ管理ツールです。未導入なら brew.sh の 1 行コマンドで先に入れてください。cmux hooks setup は 1 回だけ実行すれば OK です。

✅セットアップ・チェックリスト

✓brew でインストール — brew install --cask cmux ✓通知フックを有効化 — cmux hooks setup ✓最初の並列実行 — ⌘N で作って claude を起動

基本のキ・最初の3操作

難しいことは後回し。この 3 つだけ覚えれば、もう並列エージェントを回せます。

① 作業を分ける

⌘N で新しいワークスペースを作る。案件・タスクごとに 1 枚。

② エージェントを起動

各ワークスペースで claude や codex を起動。これで並列に走り始めます。

③ 光ったら反応

青いリングが光ったら ⌘⇧U。「最新の未読」に一瞬で飛べます。

💡

ヒント：とりあえず ⌘N（作る）・⌘1〜⌘8（切り替え）・⌘⇧U（呼ばれた所へ）の 3 つを手に覚えさせるのが上達の近道です。

4つの基本用語

cmux の画面は 4 つの単位でできています。これさえ分かれば迷いません。

用語	かんたんに言うと	イメージ
ワークスペース	作業の単位。案件・タスク 1 つ＝1 枚	左サイドバーの縦タブ
サーフェス（タブ）	ワークスペース内の「画面」。複数持てる	1 枚の中のタブ
ペイン	画面の分割枠。ターミナルやブラウザを入れる	左右・上下に割った枠
通知リング	状態を示す色の丸。緑＝実行中 / 青＝あなた待ち / 灰＝待機	ペイン・タブの丸い印

🔰

初心者向け：「1 案件＝1 ワークスペース、その中をペインで分けてターミナル＋ブラウザを並べる」——この型を覚えれば 9 割の作業はカバーできます。

最初の1日フロー

案件ごとにワークスペースを分けて、リングが光ったら対応する。これだけで回ります。

案件ごとにタブ

⌘N でワークスペース作成。タスク単位で分けると迷子になりません。

エージェント起動

各タブで claude / codex / gemini を起動。並列で走り始めます。

ブラウザを並べる

⌘D で分割し、内蔵ブラウザに localhost を表示。結果を即確認。

リングに反応

青く光ったら ⌘⇧U で対応。放置ゼロで全エージェントを回し続けます。

⚠️

注意：最初から欲張って 10 体動かさないこと。まずは 2〜3 体で「光ったら対応」のリズムに慣れてから増やすと、破綻しません。

機能別・使い方ガイド

主要機能を 3 点セットで構造化しました。カードをクリックすると開きます（先頭は最初から開いています）。

通知リングを使いこなす

cmux の心臓部です。色の意味と「未読へジャンプ」を覚えれば、放置ゼロで複数エージェントを回せます。

🔵リングの色の意味

色	状態	あなたがすること
● 緑	実行中（エージェントが作業中）	待つ。覗かなくてOK
● 青	入力待ち・完了（あなた待ち）	`⌘⇧U` で飛んで対応
● 灰	待機（指示待ち・idle）	次のタスクを投げる

⌨️覚えるショートカット

通知パネルを開く … ⌘I
最新の未読へジャンプ … ⌘⇧U（最重要）

💡

ヒント：通知は OSC 9 / 99 / 777 と cmux notify に対応。自作スクリプトからも通知を出せます（Lv.3 参照）。

⚠️

通知が来ない時：① cmux hooks setup を実行したか ② OSC に対応したシェルか、を確認してください。

内蔵ブラウザで動作確認

cmux にはアプリ内ブラウザが入っています。エージェントの隣に localhost を並べて、書いた瞬間に結果を見られます。

ブラウザを開く … ⌘⇧L ／アドレスバー … ⌘L
戻る / 進む … ⌘[ / ⌘] ／リロード … ⌘R
DevTools（開発者ツール） … ⌥⌘I ／コンソール … ⌥⌘C

🔑ログイン済みで始める「ブラウザインポート」

Chrome / Firefox / Arc など 20 以上のブラウザから cookie・履歴を読み込めます。これにより、ペインを最初からログイン済みの状態で開けます。

🔰

初心者向け：DevToolsはブラウザの「中身を見る道具」。要素の確認・エラーログ・ネットワーク状況などをチェックできます。困ったらまず ⌥⌘C でコンソールのエラーを見ましょう。

⚠️

制約（WKWebView 由来）：viewport エミュレーション・オフライン・ネットワークモック・トレース記録は非対応です。これらが必要なテストは外部の Playwright 等を併用してください。

CLI・socket APIで自動化

ワークスペースやペインの生成・通知・セッション制御を、すべてコマンドから操作できます。チーム標準のレイアウトをスクリプトで配布できます。

🗂️ワークスペース / ペイン

# 作業ディレクトリを指定して新規ワークスペース $ cmux new-workspace --cwd ~/path $ cmux rename-workspace "api-refactor" # 右に分割（down で下に分割） $ cmux new-split right

🔔通知（自作スクリプトから光らせる）

$ cmux notify --title "Build" --subtitle "myapp" --body "Tests passed" $ cmux clear-notifications # OSC シーケンスでも通知可（OSC 9/99/777 対応） $ echo -e "\033]777;notify;タイトル;本文\033\\"

🪝フック / 現在地の特定

$ cmux hooks setup # 通知・resume 連携を導入 $ cmux identify --json # 今いる workspace/window/surface を取得

💡

ヒント：cmux identify --json をスクリプトに組み込むと、「今いるペインに対してだけ通知」といった文脈付きの自動化が書けます。

ブラウザ自動化API（エージェントのUI検証）

内蔵ブラウザは Playwright 相当のスクリプタブル API を持ち、アクセシビリティツリーを使った安定操作ができます。エージェントが「自分で画面を触って」動作確認します。

🧭基本操作

$ cmux browser open http://localhost:3000 $ cmux browser navigate <url> $ cmux browser get-url # アクセシビリティツリー＋要素ref(e1,e2…)を取得（surface 指定） $ cmux browser <surface> snapshot --interactive

🖱️要素操作・入力

$ cmux browser <surface> click <ref> --snapshot-after $ ... fill <ref> "text" ... type "text" $ ... select <ref> "value" ... press "Enter" ... scroll

⏳待機・取得

$ ... wait --load-state complete --timeout-ms 15000 $ ... wait --selector "<css>" --text "<文字>" --url-contains "<path>" $ ... get text <selector> get html <selector> get value <ref> eval "<js>"

💡

推奨の安定ループ：navigate → get url で確認 → wait --load-state complete → snapshot --interactive で新しい ref を取得 → click / fill → 再 snapshot で検証。ref は操作のたびに変わるので、毎回 snapshot を取り直すのがコツです。

SSH・セッション復元・Claude Teams

🛰️リモート作業（cmux ssh）

cmux ssh user@host でリモート環境に接続。localhost トラフィックはリモート網へルーティングされ、画像をドラッグ&ドロップすると scp で自動アップロードされます。

$ cmux ssh user@host

💾セッション復元・resume 制御

$ cmux restore-session # レイアウトごと前回を復元 # 任意の resume（例: tmux セッションへ再接続） $ cmux surface resume set --kind tmux --checkpoint work --shell "tmux attach -t work" $ cmux surface resume show --json $ cmux surface resume clear --checkpoint work

⚠️

注意：エージェントの自動 resume を止めたい場合は ~/.config/cmux/cmux.json に {"terminal":{"autoResumeAgentSessions":false}} を設定します。

🤝Claude Code Teams

cmux claude-code-teams で、チームメイト（複数の Claude）を分割ペインに一括展開。サイドバーにメタ情報＋通知が並び、「10 体の Claude」を一画面で監督できます。

$ cmux claude-code-teams

⌨️ ショートカット練習器（さわって覚える）

読むだけでは身につきません。「見る」で対応キーを光らせ、「練習」で実際にキーを押して覚えましょう。下のキーボードはクリックでも反応します。

表でホバー／キーをクリックすると、ここに対応が表示されます。

ショートカット完全早見表

カテゴリ別に、公式のキーバインドをすべて掲載します。

🧠 ショートカットを最短で手に覚えさせるノウハウ

丸暗記は不要です。cmux のキーバインドは 修飾キーに意味の法則があるので、ルールで覚えると一気に楽になります。

🔑

法則① 修飾キーで“対象”がわかる：⌘＝ワークスペース操作、⌃（Control）＝タブ（サーフェス）操作、⌥⌘＝ペインのフォーカス移動。「いま何を動かしたいか」で押す指が決まります。

➕

法則② ⇧ を足すと“強い・逆”の操作：⌘N（新規）→ ⌘⇧N（新規ウィンドウ）、⌘D（右に分割）→ ⌘⇧D（下に分割）、⌘,（設定）→ ⌘⇧,（設定リロード）のように、⇧ ＝もう一段踏み込むと覚えると派生が一気に増えます。

🔰

覚える順番（最初の1週間）：1日目 ⌘N・⌘1〜⌘8・⌘⇧U の3つだけ。3日目 分割の ⌘D／⌘⇧D とフォーカス移動 ⌥⌘＋矢印。1週間目 ブラウザ系（⌘⇧L・⌘L）。使う順に少しずつが定着の近道です。

⚠️

迷いやすいペア：「タブの番号切替」は ⌃1〜⌃8（Control）、「ワークスペース切替」は ⌘1〜⌘8（Command）。⌘＝大きい単位、⌃＝その中のタブと紐づけると混乱しません。また ⌘L はブラウザにフォーカス中はアドレスバーになります。

🎯

指で覚えるなら：上の「⌨️ ショートカット練習器」の練習モードで出題に答えると、見て覚えるより数倍速く定着します。詰まったキーだけ繰り返し出るので、苦手潰しに最適です。

CLIコマンド早見表

よく使う cmux コマンドを目的別に。

目的	コマンド

FAQ（初心者向け）

よくある疑問に先回りで答えます。

印刷用 A4 クイックリファレンス

印刷 / PDF 保存して、チームのデスクに 1 枚。新メンバーのオンボーディングに。

cmux クイックリファレンス並列 AI エージェント・ターミナル — 初心者ガイド

INTERNAL USE
macOS / Homebrew
github.com/manaflow-ai/cmux

導入

インストールbrew install --cask cmux
通知フックcmux hooks setup
設定継承~/.config/ghostty

必須ショートカット

新規ワークスペース⌘N
ワークスペース切替⌘1–8
右 / 下に分割⌘D / ⌘⇧D
ペイン移動⌥⌘ ←↑↓→
最新の未読へ⌘⇧U

覚えると速い

ブラウザを開く⌘⇧L
通知パネル⌘I
検索 / ディレクトリ検索⌘F / ⌘⇧F
DevTools⌥⌘I
文字サイズ ± / リセット⌘± / ⌘0

使い方のコツ

案件ごとにワークスペースを分ける（混ぜない）
青いリング＝あなた待ち。即 ⌘⇧U
ターミナル＋ブラウザを分割で常時表示
cmux claude-code-teams でチーム並走
困ったら cmux restore-session で復元

cmux 初心者向けユーザーズマニュアル出典: github.com/manaflow-ai/cmux · cmux.com