#Workspace Groups

Workspace groups let you nest workspaces into collapsible named sections in the sidebar. Each group has an implicit anchor workspace, a customizable + button for spawning new workspaces inside it, and right-click actions for renaming, pinning, ungrouping, and editing its configuration.

#Concepts

#Anchor workspace

Every group is owned by exactly one workspace called the anchor. The group header in the sidebar is the anchor's representation — there is no separate row for it. Clicking the header name area focuses the anchor's panels; clicking the chevron toggles collapse.

Anchors are always brand new when a group is created. They are never promoted from an existing workspace. The anchor's working directory is inherited from the first selected workspace when grouping a selection, or from the active workspace when creating via the CLI without --cwd.

Closing the anchor workspace dissolves the group: every other member becomes an ungrouped workspace and stays in the tabs list. Nothing is closed besides the anchor itself. The app shows a confirm dialog with a "Don't ask again" toggle before this happens.

#Group identity

A group has a name, an icon (an SF Symbol, default folder.fill), and an optional custom color. These are independent of the anchor workspace's own customizations. The anchor's color and icon are seeded from the group on creation, but they can diverge afterwards.

#Pinning

Groups can be pinned independently of individual workspace pins. Pinned top-level rows, whether individual workspaces or groups, stay above unpinned rows. Within each tier, groups and workspaces keep the order you drag them into.

The sidebar lays out top-level rows top to bottom:

Pinned top-level rows (workspaces and groups).
Unpinned top-level rows (workspaces and groups).

#Creating a group

A group is created from a keyboard shortcut or a sidebar context menu. Empty groups insert a fresh anchor workspace as the group header. Selection-based groups insert that anchor above the selection and move the selected workspaces into the group. Once a group exists, you manage it and add workspaces to it from the group header (see Managing a group below).

#From keyboard shortcuts

Press ⌃⌘G to create a new empty workspace group. Select two or more workspaces in the sidebar, then press ⌘⇧G to group the selection. Both paths create a fresh anchor workspace and auto-name the group Group 1, Group 2, and so on. Rename it anytime via the header context menu.

⌘⇧G collides with React Grab's default. The group handler only consumes the chord when there is an explicit sidebar multi-selection of at least two workspaces, so React Grab still fires in single-selection and in browser or terminal contexts. Rebind it in Settings → Keyboard if you would rather the two not share a key.

Single-tab groups are not created from the shortcut. Use the workspace context menu New Group from Workspace entry for that.

Right-click any workspace in the sidebar and choose New Empty Workspace Group, New Group from Workspace, or New Group from Selection when multiple workspaces are selected. The blank area below the sidebar list also offers New Empty Workspace Group. These paths use the same auto-naming behavior as the shortcuts.

#Managing a group

Once a group exists, its header context menu and the + button on the header let you manage the group and add workspaces to it. Neither creates a new group.

#From the group header context menu

Right-click an existing group header for Rename Group…, Pin Group / Unpin Group, Edit Group Config… (which opens ~/.config/coterm/coterm.json), Open Workspace Groups Docs, Ungroup (Keep Workspaces), and Delete Group (Close Workspaces). Delete is destructive and prompts for confirmation; ungroup keeps the workspaces and just removes the container.

#From the + button on a group header

Hover over a group header to reveal a trailing + button. Click it to create a new workspace in the group at the anchor working directory. Right-click it for New Workspace in Group, Edit Group Config…, and Open Workspace Groups Docs.

Pressing ⌘N while the active workspace is a group anchor or member also creates the new workspace inside that group. The default placement is After current: from a regular group member the new workspace lands right after the active member, and from the anchor or header it lands at the top of the group.

#CLI

All group operations are scriptable with the coterm workspace-group subcommands. The hyphenated form ships first; once the broader coterm workspace command namespace lands, coterm workspace group becomes the canonical form, with the hyphenated form kept as an alias forever.

#Subcommands

coterm workspace-group list [--json]
coterm workspace-group create --name "emergent.inc" [--cwd ~/projects/emergent.inc] [--from <id>,<id>]
coterm workspace-group ungroup <group-id>
coterm workspace-group delete  <group-id>
coterm workspace-group rename <group-id> --name "new name"
coterm workspace-group collapse <group-id>
coterm workspace-group expand <group-id>
coterm workspace-group pin <group-id>
coterm workspace-group unpin <group-id>
coterm workspace-group add --group <group-id> --workspace <workspace-id>
coterm workspace-group remove --workspace <workspace-id>
coterm workspace-group set-anchor --group <group-id> --workspace <workspace-id>
coterm workspace-group new-workspace <group-id> [--placement afterCurrent|top|end]
coterm workspace-group set-color <group-id> --hex "#7A4FD8"
coterm workspace-group set-icon  <group-id> --symbol ladybug.fill
coterm workspace-group move <group-id> (--to-index <n> | --before <group-id> | --after <group-id>)
coterm workspace-group focus <group-id>

create returns a group handle (workspace_group:N by default). Pass --json for the full structured payload.

Pass set-color or set-icon an empty value to clear the group's color or icon. delete is irreversible: it closes every member workspace.

#Examples

Group the currently selected workspaces under a name:

coterm workspace-group create --name emergent.inc

Spin up a new workspace inside an existing group, for example wired to a worktree script:

coterm workspace-group new-workspace workspace_group:1

List groups in the focused window:

coterm workspace-group list

#Configuration

Per-group configuration lives under the workspaceGroups key in ~/.config/coterm/coterm.json, keyed by the anchor workspace's working directory. See the configuration reference for the supported keys, including the global new-workspace placement and per-directory color, icon, placement, and context-menu actions.

workspaceGroups configuration reference

#Persistence

Group name, anchor, pin state, collapse state, color, and icon are saved alongside your workspaces and restored across launches. Group membership is stored on each workspace.