cmux-groups

cmux ワークスペースグループ

ワークスペースグループは、cmux サイドバーで折りたたみ可能な名前付きセクションです。各グループはアンカーワークスペースが所有します。グループのヘッダーはアンカーのサイドバー上の表示を兼ねているため、アンカー用の行は別にありません。アンカーを閉じるとグループは解消され、他のメンバーはグループ化されていないワークスペースとして残ります。

CLI

標準的な名詞形を使用してください：

cmux workspace group list [--json]
cmux workspace group create --name <name> [--cwd <path>] [--from <id>,<id>]
cmux workspace group ungroup <group-id>
cmux workspace group delete <group-id>
cmux workspace group rename <group-id> --name <new>
cmux workspace group collapse <group-id>
cmux workspace group expand <group-id>
cmux workspace group pin <group-id>
cmux workspace group unpin <group-id>
cmux workspace group add --group <group-id> --workspace <workspace-id>
cmux workspace group remove --workspace <workspace-id>
cmux workspace group set-anchor --group <group-id> --workspace <workspace-id>
cmux workspace group new-workspace <group-id> [--placement afterCurrent|top|end]
cmux workspace group set-color <group-id> [--hex #RRGGBB]
cmux workspace group set-icon <group-id> [--symbol <sf-symbol>]
cmux workspace group move <group-id> --to-index <n> | --before <group-id> | --after <group-id>
cmux workspace group focus <group-id>

cmux workspace-group ... は、同じ操作を行うための互換性エイリアスです。<group-id> には UUID または workspace_group:1 のような参照を指定できます。すべてのコマンドで --json を使用できます。

create は新しいアンカーワークスペースを作成します。既存のワークスペースをアンカーに昇格させることはありません。--from には、新しいアンカーの下に子として追加するワークスペースを指定します。--from を省略した場合、利用可能であれば cmux はアクティブなサイドバー選択項目または呼び出し元のワークスペースを使用します。

ungroup はアンカーを含むすべてのメンバーのワークスペースを維持したまま、グループを解消します。アンカーは通常のグループ化されていないワークスペースになります。delete は破壊的な操作であり、グループ内のすべてのワークスペースを閉じます。

new-workspace はグループの新規ワークスペース作成動作を実行します。新しいワークスペースはアンカーの cwd に作成され、グループに追加されます。配置は明示的に指定するか、cwd ごとの設定またはグローバルなグループのデフォルトから解決できます。

Socket methods

CLI は v2 JSON ソケット API の薄いラッパーです。CLI から呼び出せる操作はすべて直接呼び出すこともできます：

workspace.group.list
workspace.group.create        { name, cwd?, child_workspace_ids? }
workspace.group.ungroup       { group_id }
workspace.group.delete        { group_id }
workspace.group.rename        { group_id, name }
workspace.group.collapse      { group_id }
workspace.group.expand        { group_id }
workspace.group.pin           { group_id }
workspace.group.unpin         { group_id }
workspace.group.add           { group_id, workspace_id }
workspace.group.remove        { workspace_id }
workspace.group.set_anchor    { group_id, workspace_id }
workspace.group.new_workspace { group_id, placement? }
workspace.group.set_color     { group_id, hex? }
workspace.group.set_icon      { group_id, symbol? }
workspace.group.move          { group_id, to_index? | before_group_id? | after_group_id? }
workspace.group.focus         { group_id }

すべての操作で標準の window_id / window_ref パラメーターを受け付けており、フォーカスされていないウィンドウを対象にできます。

設定（~/.config/cmux/cmux.json）

グループごとの設定は、アンカーの cwd をキーとして指定します。* または ? を含むキーは ~ の展開に対応した fnmatch グロブです。それ以外のキーはパスのプレフィックスです。最長一致が優先されます。

{
  "workspaceGroups": {
    "newWorkspacePlacement": "afterCurrent",
    "byCwd": {
      "/abs/path/to/repo": {
        "color": "#7A4FD8",
        "icon": "ladybug.fill",
        "newWorkspacePlacement": "top",
        "contextMenu": [
          { "action": "newWorktreeAction", "title": "New Worktree" },
          { "action": "newWorkspace" }
        ]
      },
      "~/projects/*": {
        "icon": "leaf.fill",
        "newWorkspacePlacement": "end"
      }
    }
  }
}

workspaceGroups.newWorkspacePlacement と workspaceGroups.byCwd[...].newWorkspacePlacement には、次の値を指定できます：

• afterCurrent：グループ内でアクティブなワークスペースの後ろに配置します。アクティブなメンバーの参照がない場合は、先頭に配置します。
• top：アンカーのすぐ後ろの2番目のスロットに配置します。
• end：最後のメンバーの後ろに配置します。

グループ内の新規ワークスペースの配置は、次の順序で解決されます：

1. CLI の明示的な --placement afterCurrent|top|end、または workspace.group.new_workspace の "placement"。
2. cwd ごとの workspaceGroups.byCwd[...].newWorkspacePlacement。
3. グローバルな workspaceGroups.newWorkspacePlacement。
4. 組み込みのデフォルト afterCurrent。

グループ内で Cmd-N を押すと、アクティブなグループ内ワークスペースが配置の基準として使用されます。グループヘッダーの + ボタンと CLI の操作では、アンカーが基準として使用されるため、ここでは afterCurrent は top と同じ動作になります。

グループのコンテキストメニュー項目には、ui.newWorkspace.contextMenu と同じスキーマを使用します。アクションはグローバルな actions ブロックで定義するか、newWorkspace のような組み込みアクションを使用する必要があります。

Keyboard

デフォルトのショートカットは Cmd-Shift-G で、サイドバーで選択したワークスペースをグループ化します。サイドバーで選択されているワークスペースがない場合は、フォーカス中のワークスペースを使用します。Settings > Keyboard でショートカットを再設定できます。

Anchor semantics

• アンカーの識別情報はワークスペースのフラグではなく、グループ（anchorWorkspaceId）に保持されます。
• アンカーはグループのヘッダーとして表示され、サイドバーに個別の行はありません。
• アンカーを閉じると、確認ダイアログの後にグループが解消されます。
• set-anchor はアンカーとなるメンバーを再割り当てします。以前のアンカーワークスペースは、独自のサイドバー行を持つ通常のメンバーになります。

Persistence

グループとメンバー構成は、既存の SessionPersistenceStore を通じて ~/Library/Application Support/cmux/session-<bundle-id>.json に保存・復元されます。書き込みには、配置先へのアトミックなリネームを使用します。WAL はありません。

Rules

• セッション JSON の編集より、CLI またはソケット操作を優先してください。
• 今後サポートされる予定の未対応設定キーを書き込まないでください。不明な場合は、cmux の web/data/cmux.schema.json を確認してください。
• スクリプトで操作する際は、アンカーのセマンティクスを維持してください。グループを移動する場合は、子ワークスペースの行だけでなく、アンカーセクションを移動します。
• ワークスペースを残す場合は ungroup を使用してください。グループ内のすべてのワークスペースを閉じる場合に限り、delete を使用してください。