cmuxとは｜Codex・Claude Codeの通知をフック注入で束ねるGhostty製ターミナル

cmuxは、複数のAIコーディングエージェントを同時に走らせることを前提に設計されたmacOS専用のターミナルアプリだ。エージェントを並列で動かし始めると、まず「どれが止まっているか分からない」という問題にぶつかる。Claude Codeの通知本文はどれも同じ、タブを増やせばタイトルは読めなくなる——ターミナルの側には、そのペインの中で動いているプロセスが「作業中」なのか「入力待ち」なのかを知る手段がそもそも無いからだ。

manaflow-ai/cmux（★25,470・Swift／2026年8月2日時点）は、この情報をエージェント本体から取りに行くという方法で解いている。各コーディングエージェントの設定ファイルに、cmux自身がフックを書き込む。以下では公式ドキュメントとソース、そして実際に配布物を動かした結果をもとに、その仕組みの範囲と限界を整理する。

なおAIコーディングの前提——エージェントに任せる範囲の決め方やツールの選び分け——を先に押さえたい場合は、Vibe Codingとは？AIコーディングの始め方・ツール比較・実践ワークフロー2026を読んでおくと、本記事が扱う「端末レイヤー」の位置づけが掴みやすい。

cmuxとは——並走させたときに壊れるのは「状態の可視性」

cmuxの出発点は作者自身の運用だ。READMEの「Why cmux?」節は、Claude CodeとCodexを大量に並列実行していたこと、Ghostty上で分割ペインを並べてmacOS標準通知に頼っていたこと、そしてClaude Codeの通知本文が常に “Claude is waiting for your input” で文脈を持たないため、タブが増えるとタイトルすら読めなくなったことを挙げている。

ここで効くのが、ターミナルエミュレータには本来「中で動いているプロセスの意味論」が見えないという構造的な制約だ。ペインに流れてくるのはバイト列であって、「このエージェントはツールの実行許可を待っている」といった状態ではない。だからcmuxは、その情報をエージェント側から供給させる設計を採った。

READMEが挙げる主な構成要素は次のとおり。いずれも公式の記述であり、性能面の主張（「Electronではない・高速起動・低メモリ」など）はREADMEの主張としてそのまま扱う。

・通知リング：エージェントが注意を要する状態になるとペインに青い枠が付き、サイドバーのタブが点灯する
・通知パネル：保留中の通知を一覧し、最新の未読へジャンプする（Cmd+Shift+U）
・アプリ内ブラウザ：vercel-labs/agent-browserから移植したスクリプタブルAPIを備え、アクセシビリティツリーのスナップショット取得・要素参照・クリック・フォーム入力・JS評価ができる
・縦＋横タブ：サイドバーにgitブランチ、紐づくPRのステータスと番号、作業ディレクトリ、待ち受けポート、最新の通知テキストを表示
・SSH：cmux ssh user@remoteでリモートマシン用のワークスペースを作る。ブラウザペインはリモート側のネットワークを経由するため、localhostがそのまま解決される
・Ghostty互換：既存の~/.config/ghostty/configからテーマ・フォント・配色を読み込む

残りの2つは、エージェントに実際に作業をさせるときに効いてくる補助機能だ。ひとつはブラウザインポートで、Chrome・Firefox・Arcなど20以上のブラウザからCookie・履歴・セッションを取り込み、ブラウザペインを認証済みの状態で開始できるとREADMEは説明している。エージェントに開発中のアプリを触らせるとき、ログイン画面で止まらないようにするための機能だ。もうひとつはカスタムコマンドで、プロジェクト固有のアクションをcmux.jsonに定義しておくとコマンドパレットから起動できる。

そしてこれら全体がCLIとsocket APIから操作できる、というのがcmuxの設計上の主張だ。ワークスペースの作成、ペインの分割、キーストロークの送信、ブラウザの自動化までがスクリプトから叩ける。READMEの「The Zen of cmux」節は、この方針を「cmuxは解決策ではなくプリミティブである」「開発者がツールをどう持つべきかについて指図しない」と表現している。エージェント運用の型が定まっていない現状では、決め打ちのGUIオーケストレータよりも素材を配るほうがよい、という立場だ。

インストールと動作要件——macOS 14以上・Sparkleによる自動更新

配布はDMGとHomebrew caskの2経路。Homebrew公式APIのcask定義を確認すると、2026年8月2日時点でバージョンは0.64.20、依存はmacos >= 14だった。これはGitHub Releasesの最新安定版v0.64.20（2026年7月19日公開）と一致する。

# Homebrew cask 経由（tap が必要）
brew tap manaflow-ai/cmux
brew install --cask cmux

# 更新
brew upgrade --cask cmux

DMGで入れた場合もSparkle経由で自動更新されるため、ダウンロードは初回のみでよいとREADMEは説明している。初回起動時に「識別された開発元のアプリ」の確認ダイアログが出る場合がある。

リリース群を見ると、安定版タグ（v0.64.20、v0.64.19）とは別にnightlyというプレリリースが置かれており、そこには717個のアセットがぶら下がっていた。日次ビルドを1つのタグに積み上げる運用と見られる。安定版を使いたい場合は、nightlyではなくバージョンタグ側の資産を選ぶ必要がある。

フック注入の仕組み——cmuxが各エージェントに書き込むもの

ここがcmuxの中核であり、単なる「見た目のいいターミナル」と分かれる部分だ。docs/agent-hooks.mdは、cmuxがエージェントフックを使って実行状態・承認・通知の表示と、アプリ再起動後のセッション復帰を実現していると明記している。

# 全エージェントを一括セットアップ（PATH に無いものはスキップして要約を表示）
cmux hooks setup

# 個別に指定
cmux hooks setup codex
cmux hooks uninstall codex

cmux hooks setupに渡せるエージェント名として公式ドキュメントが列挙しているのは次の16個だ。codex・grok・opencode・pi・omp・campfire・amp・cursor・gemini・kimi・kiro・rovodev（またはrovo）・copilot・codebuddy・factory・qoder。統合一覧の表はこれにClaude Codeを加えた17行になっており、Claude Codeだけはhooks setupではなく「Claude Code連携を設定で有効にしたときにcmuxのClaudeラッパーが処理する」という別扱いになっている。16と17という2つの数字は矛盾ではなく、数え方の違いだ。

重要なのは、cmuxが書き込む先がcmux自身の設定ではなくエージェント側のホームディレクトリ配下である点だ。主要なものを抜き出すと次のようになる。

この表から読み取れる実務上の含意は2つある。第一に、cmuxを入れるとエージェントの設定ファイルが書き換わる。どのファイルが対象かは事前に把握しておいたほうがよい。第二に、対応の粒度は一律ではない。Kimi Codeはフック自体は入るがセッション復帰が「未対応」と明記されているように、エージェントごとに実装の到達点が違う。

フックが記録する内容も文書化されている。セッションフックは~/.cmuxterm/<agent>-hook-sessions.jsonに書き込み、各エントリはエージェントのセッションID、cmuxのワークスペースID、サーフェスID、作業ディレクトリ、取得できた場合はプロセスID、現在のライフサイクル（running・idle・needsInput・unknown）、そしてサニタイズ済みの起動コマンドを保持する。

このサニタイザの挙動は、セキュリティ上そのまま読む価値がある。ドキュメントは「モデル・サンドボックス・設定・作業ディレクトリ関連のフラグは保持し、プロンプト・認証情報・古いセッションセレクタ・非対話コマンドは落とす」と述べている。復帰時に新しいタスクを開始してしまったり、保存された文字列から秘密情報が漏れたりしないための設計だ。

通知の分類とClaude Code連携——同じ「通知」でも扱いが違う

通知は一種類ではない。CLI/AgentHookNotificationPolicy.swiftを読むと、cmuxは通知をturn-complete（ターン完了）・needs-permission（許可待ち）・idle-reminder（アイドル催促）・otherの4カテゴリに分類し、状態としてはidle・needsInput・errorを持っている。「エージェントが終わった」と「エージェントが許可を求めている」を同じ扱いにしないための区別だ。

取り込み経路も複数ある。READMEはターミナルのエスケープシーケンス（OSC 9 / 99 / 777）を拾うことと、エージェントのフックに繋ぎ込めるcmux notifyというCLIがあることの両方を挙げている。つまり、フック統合が用意されていないツールでも、OSCを吐くかcmux notifyを呼ぶかすれば通知に載せられる。

Claude Codeについては、もう一段込み入った処理が書かれている。Claude CodeのPushNotificationツール（モデル側から「今ユーザーに知らせる」と判断して出すもの）は、PostToolUseフックを介してcmuxの通知へ橋渡しされる。ドキュメントによれば、このツールは通常は生のOSCデスクトップ通知で配信するが、cmuxはフック統合済みエージェントが動いているサーフェス上ではそれを抑制する。したがってこのブリッジが無いとプッシュがcmux内で見えなくなる、という関係になっている。さらに、ツール自身が「スキップした」（ユーザーがアクティブ、チャネルが無効など）と報告したプッシュは重複表示しない、という挙動まで揃えている。

Grokの扱いも対照的で面白い。cmuxはStopをidle状態として記録する一方、表示される通知テキストはNotificationペイロードに委ねる。こうすることで、ターンを繰り返してもGrok自身のメッセージが汎用の「完了しました」的なフォールバックに上書きされない。

cmux claude-teamsはClaude Codeのチームメイトモードを1コマンドで起動する機能で、チームメイトはネイティブの分割ペインとして生成され、サイドバーのメタデータと通知が付く。READMEはここに「tmuxは不要」と明記している。Claude Code固有の機能まわりを詳しく追うなら、同じくターミナル側からエージェントを束ねるWarp とは｜Rust製AIターミナルでClaude Code・Codexを動かす使い方とOSS化の中身と読み比べると設計の差が見えやすい。

なおワークスペースの自動命名（automation.workspaceAutoNaming、オプトイン）は対応範囲がさらに狭い。ドキュメントが対応アダプタとして挙げるのはClaude Code・Codex・Grok・OpenCode・Pi・OMPの6つで、Gemini・Amp・Cursor・Antigravity・Kiro・Rovo Dev・Hermes Agent・Copilot・CodeBuddy・Factory・Qoderは「検証済みの会話ソースと安全で安価な非対話サマライザが揃うまで」スキップされると明記されている。フックが入ることと、その上の機能が全部使えることは別だ。

セッション復帰とAgent Hibernation——既定値は12・5秒・約60秒

フックでセッションIDとサーフェスの対応を持っていることの応用が、Agent Hibernationだ。アイドル状態のバックグラウンドエージェントのプロセスを終了させてRAMとCPUを解放し、そのタブに戻ったときに保存済みセッションで復帰させる。cmuxがどのプロセスがどのターミナルのものかを知っているのは、前節のフックがセッションIDとサーフェスを結び付けているからだ、とドキュメントは説明している。

ここで安定版とmainブランチでドキュメントの記述が食い違っている点は、使う側にとって実害があるので分けて書く。

安定版v0.64.20のタグに含まれるdocs/agent-hooks.mdは、Agent Hibernationについて「オプトインで既定オフ」とだけ述べている。一方mainブランチの同ファイルは、その文を「通常のハイバネーション（ライブターミナル上限に基づくもの）がオプトインで既定オフ」と限定し直したうえで、「重度のメモリ逼迫に対する別の限定的な安全経路は有効なままである」と追記している。さらに「Critical memory pressure」という節が新設され、macOSが重度のメモリ逼迫を報告した場合、enabled設定とライブターミナル上限とは無関係に同じ保護付き終了経路を走らせうること、1回のパスで選ぶのは最も長くアイドルなバックグラウンドエージェント最大2つまでであることが書かれている。

通常のハイバネーションが発火する条件は、安定版・mainとも次のすべてを満たす場合に限られる。

・復帰可能なエージェントセッションが保存済みで、保存された起動データから復帰コマンドを構築できる
・エージェントのライフサイクルがidle（実行中でも入力待ちでもない）
・そのターミナルがバックグラウンド（パネルが表示されていない）
・復帰可能なライブエージェントターミナル数が上限maxLiveTerminals（既定12）を超えている
・出力・入力・ライフサイクル変化のいずれもidleSeconds（既定5）以上発生していない

そのうえで終了前に「確認ウィンドウ」がある。cmuxは出力の末尾数行とプロセスのフィンガープリントをサンプリングし、約60秒（confirmationSeconds）のあいだ出力もプロセスも変わらないことを確認する。新しい出力・入力・ライフサイクル変化・PID変化があれば保留中のハイバネーションは取り消される。idleSecondsの既定が5秒と短くても安全なのはこの二段構えのためだ、とドキュメントは説明している。

実際に終了させるときはワークスペースとサーフェスにスコープしたうえでプロセスグループにSIGTERMを送り、ライブターミナルを軽量なプレースホルダに差し替える。タブに戻るとエージェント固有の復帰コマンドが保存済みセッションIDで実行される。プレースホルダには手動フォールバック用のResumeボタンも出る。

設定はコマンドパレット（⌘⇧P → Enable Agent Hibernation）、設定画面、CLI、または設定ファイルから行える。

cmux agent-hibernation on
cmux agent-hibernation off

~/.config/cmux/cmux.jsonで閾値を直接指定する場合は次の形になる。idleSecondsは5〜604800、maxLiveTerminalsは1〜256の範囲だ。

{
  "terminal": {
    "agentHibernation": {
      "enabled": true,
      "idleSeconds": 5,
      "maxLiveTerminals": 12
    }
  }
}

既定値のまま使う限り、通常のハイバネーションが影響するのは12個を超えるエージェントを同時に走らせている場合で、しかも画面外で静かになってから約1分後だ——というのがドキュメントの説明である。

npx cmuxは同名の別物——実測で切り分ける

ここが最も誤解を招きやすい部分なので、実際に動かして確認した。npmにはcmuxというパッケージが存在し、npx cmuxで起動できる。メタデータのrepositoryはgit+https://github.com/manaflow-ai/cmux.git、directoryはcmux-tui/dist/npm/cmuxを指しており、同じリポジトリのcmux-tuiディレクトリの成果物であることが確認できる。

ところが中身は別プロダクトだ。まずバージョンが一致しない。

$ npx --yes [email protected] --version
cmux-tui 0.1.0 (ce84b6ffa0bc135adb5d5e6b520068b244c974c2; ghostty 0b1734f1eeca32ff6e0c17af2c95641639e682ba)

npm上のバージョンは0.9.9なのに、バイナリは自身をcmux-tui 0.1.0と名乗る。併記されたコミットハッシュce84b6ffをGitHub APIで引くと同リポジトリに実在し、コミット日時は2026年7月28日20:13(UTC)、npmの公開時刻は同日20:49(UTC)だった。36分差なので、このコミットからビルドして公開したものと読める。

決定的なのはコマンド面の差だ。macOSアプリの目玉であるhooksは、TUI側には存在しない。

$ npx --yes [email protected] hooks
cmux-tui: unknown argument "hooks"
$ echo $?
2

$ npx --yes [email protected] notify
cmux-tui: --title is required
$ echo $?
2

hooksは「unknown argument」で弾かれる一方、notifyは「--titleが必要」というエラーを返す。つまり通知のプリミティブ（notify）は共通だが、各エージェントの設定ファイルへフックを書き込む機構（hooks setup）はmacOSアプリ側にしかない。npx cmuxを入れて「これでCodexの入力待ちが分かるようになる」と期待すると外れる。

--helpの出力を見ると、cmux-tuiの正体はlibghostty-vtをバックエンドに持つtmux類似のマルチプレクサだ。プレフィックスキーはCtrl-b（tmuxと同じ既定）で、%で右分割、"で下分割、zで最大化、dでデタッチという操作体系を持つ。ビルドにはZig 0.16.0とRust 1.91、そしてghosttyサブモジュールが必要とcmux-tui/README.mdは記している。公開CLIはcmux workspace create --name apiのような名詞優先の形で、リソースはcmux.protocol/1を通じて公開される。

npmパッケージ名の来歴も一応触れておく。cmuxの0.1.0（2025年7月12日公開）はrepositoryがgithub.com/lawrencechen/cmuxで説明は “A multiplexer tool”、0.5.0ではmanaflow-ai/cmuxに移りつつ説明は “Cloud sandboxes for development”、そして現在の0.9.9が “tmux-like terminal multiplexer TUI” になっている。同じパッケージ名の下で指すものが変わってきているため、古い情報を参照するときは注意がいる。

他ツールとの比較とライセンスの二重構造

同じ「複数エージェントを並走させる」課題を扱うツールでも、どの層で解くかが違う。cmuxと、tmux上でエージェントを統括するYoanWai/agent-manager、そして素のGhostty＋tmuxを、検証可能な軸で並べる。優劣ではなく、担当範囲の違いとして読んでほしい。

要点を一文にすると、cmuxは「エージェントが動く土台＋各エージェント設定へのフック注入」を担い、agent-managerは「tmuxセッションの統括＋差分レビューの往復」を担う。cmuxには差分レビューのループが無く、agent-managerにはフック注入の機構が無い。両者は競合というより守備範囲が違う。フック層という発想自体に関心があるなら、Codex CLIに同種の層を足すoh-my-codex（OMX）とは｜Codex CLIにHUD・チーム実行・hooksを足す使い方も比較対象になる。

ライセンスは少し込み入っている。リポジトリ直下のLICENSEは、冒頭にManaflow社の前書きを置いたうえで「ファイルまたは付随する告知が別途定める場合を除き、cmuxプロジェクトライセンスの下で提供される素材はGPL-3.0-or-laterで許諾される」と述べる。この前書きがあるためGitHub APIのライセンス判定はNOASSERTION（分類不能）を返す。READMEの機能一覧は「Open source — Free and GPL-licensed」とだけ書いている。

一方、cmux-tui側はCargo.tomlのworkspace設定でlicense = "MIT"と宣言され、npmパッケージのメタデータもMITだ。ただしcmux-tui/ディレクトリにLICENSEファイルは置かれていない（raw.githubusercontent.comへの取得はHTTP 404、GitHub Contents APIでもライセンス系ファイルは見つからない）。直下のLICENSEが想定する「ファイルまたは付随する告知が別途定める場合」に相当するのがCargo.tomlとnpmのメタデータ宣言だけ、という状態になっている。ここは配布元の原文にあたって判断すべき箇所で、本記事は確認できた事実の記述にとどめる。

開発の規模感も数字で押さえておく。GitHub検索API（2026年8月2日時点）で数えると、オープンなissueが1,602件、オープンなPRが2,329件、マージ済みPRが3,213件だった。コントリビュータ上位はlawrencecchen（4,033コミット）、austinywang（2,812）、azooz2003-bit（760）。READMEは英語のほか日本語を含む21言語が用意されているが、日本語版の冒頭には「この翻訳は Claude によって生成されました」と明記されている。同種の多言語SDKやCLIの実測比較はGitHub Copilot SDKとは｜6言語のエージェント組み込みSDKをCLI取得方式の実測で解説でも扱っている。

現在導入している設定に何が書き込まれたかを後から確認したい場合は、フックが記録するセッションストアと、各エージェントの設定ファイルを直接見るのが早い。

# cmux が記録したセッション情報（エージェントごとに1ファイル）
ls -la ~/.cmuxterm/ 2>/dev/null

# 各エージェント側に書き込まれたフックの有無を確認
grep -l cmux ~/.codex/hooks.json ~/.gemini/settings.json ~/.copilot/config.json 2>/dev/null

参照ソース

・manaflow-ai/cmux (GitHub) — リポジトリ本体。star数・fork数・言語・LICENSEの確認元
・cmux docs/agent-hooks.md — フック統合の対応表・セッションストア・Agent Hibernationの閾値
・cmux-tui README — Rust製TUIマルチプレクサのビルド要件・CLI仕様
・npm: cmux — 公開バージョン・ライセンスメタデータ・対応プラットフォーム
・Homebrew cask: cmux — 配布バージョンとmacos >= 14の依存条件