cmux-settings

cmux-settings

cmux はユーザー設定を ~/.config/cmux/cmux.json（JSONC）から読み込みます。アプリはファイル監視を行うため、ファイルを保存すると変更がすぐに反映され、再起動は不要です。従来の ~/.config/cmux/settings.json は、cmux.json に存在しないキーのフォールバックとしてのみ読み込まれます。

スキーマ：https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json。正式なパス一覧は repo/Sources/CmuxSettingsJSONPathSupport.swift にあります。トップレベルのセクションは app、terminal、notifications、sidebar、sidebarAppearance、workspaceColors、automation、browser、shortcuts です。設定以外のセクション（actions、ui、commands、vault、rightSidebar）も同じファイルに共存します。

ヘルパースクリプト

読み書きには、必ず同梱のヘルパーを使用してください。JSONC のコメントを取り除き、アトミックに書き込み、キーをスキーマに照らして検証します。

# From the installed skill directory:
./scripts/cmux-settings <subcommand>

以降、このドキュメントでは簡潔にするため、スクリプトが $PATH にあるものとして説明します。セッション中に使えるようにするには、スキルの scripts/ ディレクトリを $PATH に追加します。

export PATH="$(dirname "$(realpath "$0")")/scripts:$PATH"   # from inside the skill
# or, after installing with skills.sh:
export PATH="$HOME/.claude/skills/cmux-settings/scripts:$PATH"

サブコマンド：

コマンド	説明
cmux-settings path	設定ファイルのパスを表示します。
cmux-settings dump	ファイルの内容をそのまま表示します（コメントを保持します）。
cmux-settings dump --no-comments	解析済みの JSON を表示します。
cmux-settings get <a.b.c>	ドット区切りの JSON パスにある値を表示します。
cmux-settings set <a.b.c> <value>	値を設定します。<value> は JSON として解析されます（true、42、"text"、[…]、{…}）。引用符で囲まれていない通常の文字列は、文字列として保存されます。
cmux-settings unset <a.b.c>	キーを削除し、アプリ内のデフォルト値に戻します。
cmux-settings list-supported	アプリが認識する設定の JSON パスをすべて一覧表示します。
cmux-settings validate	ファイルを解析し、不明な設定キーがあれば報告します。
cmux-settings open	$EDITOR、VS Code、Cursor、または TextEdit で cmux.json を開きます。

--file <path> を指定すると、対象ファイルを変更できます（ユーザーが従来のファイルを使っている場合に --file ~/.config/cmux/settings.json のように指定できます）。

ワークフロー

1. 変更内容を確認します。ユーザーが設定を平易な言葉で指定した場合（例：「サイドバーの色合いをターミナルの背景色に合わせて」）、まず該当する設定を調べます。

   cmux-settings list-supported | rg -i 'sidebar.*terminal|terminal.*sidebar'
   

2. 値を設定します。JSON リテラル（true、false、数値、配列、オブジェクト）は有効な JSON である必要があります。通常の単語は文字列として保存されます。

   cmux-settings set sidebarAppearance.matchTerminalBackground true
   cmux-settings set app.appearance dark
   cmux-settings set shortcuts.bindings.toggleSidebar cmd+b
   cmux-settings set shortcuts.bindings.newTab '["ctrl+b","c"]'
   cmux-settings set browser.hostsToOpenInEmbeddedBrowser '["localhost","*.internal.example"]'
   

3. 設定を読み戻して検証し、変更を確認します。

   cmux-settings get sidebarAppearance.matchTerminalBackground
   cmux-settings validate
   

4. 自動で再読み込みされたことをユーザーに伝えます。アプリの再起動は不要です。元に戻す場合は、cmux-settings unset <key> を実行します。

クイックリファレンス

• 外観：app.appearance = "system" | "light" | "dark"、app.appIcon、app.menuBarOnly、app.minimalMode。
• サイドバーの色合い：sidebarAppearance.matchTerminalBackground、sidebarAppearance.tintColor、sidebarAppearance.tintOpacity（0..1）。
• サイドバーの詳細：sidebar.hideAllDetails、sidebar.showBranchDirectory、sidebar.showPullRequests、sidebar.showPorts、sidebar.showLog。
• 通知：notifications.dockBadge、notifications.sound（"none"、"custom_file" などの列挙型）、notifications.customSoundFilePath、notifications.hooks（配列）。
• ブラウザー：browser.defaultSearchEngine、browser.theme、browser.openTerminalLinksInCmuxBrowser、browser.hostsToOpenInEmbeddedBrowser。
• 自動化：automation.socketControlMode（off | cmuxOnly | automation | password | allowAll）、automation.portBase、automation.portRange。
• ショートカット：shortcuts.bindings.<actionId> = "cmd+b"、["ctrl+b","c"]、null、または割り当て解除を示す ""。references/shortcut-actions.md を参照してください。

設定、デフォルト値、説明の全一覧は、cmux-settings list-supported を実行するか、references/all-keys.md を参照してください。

ルール

• 編集するのは cmux.json だけです。ユーザーから明示的に依頼されない限り、settings.json は編集しないでください。これはレガシーであり、cmux.json にキーがない場合にのみ読み込まれます。
• 変更を適用するために cmux を再起動するよう、ユーザーに決して伝えないでください。ファイルウォッチャーが保存時に再読み込みします。
• 一括編集後は、必ず次のコマンドで検証してください：cmux-settings validate。不明なキーは、ユーザーがアプリで使用されないキーを貼り付けたことを意味します。
• トップレベルのセクション（actions、ui、commands、vault、rightSidebar）を無条件に上書きしないでください。これらは同じファイル内にあり、ユーザーが手動で調整した設定以外の構成も含まれています。
• ショートカットのアクション ID は、スキーマの列挙値と一致している必要があります。割り当てる前に references/shortcut-actions.md で確認してください。
• 色の値は #RRGGBB 形式で指定してください。不透明度は 0..1 です。
• ユーザーがアプリ上の表現で指定した設定（例：「設定 > 通知 > Dock バッジ」）は、まず対応する JSON パスに変換してください。repo/web/app/[locale]/docs/configuration/page.tsx のドキュメントページには、スキーマが 1 対 1 で反映されています。