Custom Session Groups (create your own collapsible sidebar sections)

What it is

What it is. A way to make your OWN sections in the left session sidebar — like the built-in NEEDS YOU, LIVE SESSIONS, or PAUSED sections — to organize your sessions however you want (e.g. "Client X", "Experiments", "Urgent"). Each custom group shows up as its own collapsible section listing the sessions you've put in it.

A group is backed by a tag: under the hood a "group" is simply a library tag you've flagged to appear in the sidebar. So you get everything the tag system already offers — per-project or global scope, colors, and a shared place to manage them — with no separate "groups" system to learn.

Where to find it

There is no separate screen for groups. You create and manage them where tags live, in Settings → Tags, and they appear as their own collapsible sections in the left session sidebar. Nothing about groups shows up at all until the tag system itself is switched on.

How it behaves

How to use it

1. Turn on Tags — this feature is part of the tag system, which is opt-in. Enable it in Settings → Tags (the setting is sessionTagsEnabled, off by default). Until tags are on, nothing about groups appears.
2. Create a group — open the tag editor (Settings → Tags → New tag, or edit an existing tag), give it a name, and turn on "Show as a sidebar group." Choose its scope: Global (the group appears in every project) or Specific projects (it appears only in those projects).
3. Add sessions to it — tag a session with that tag (a session's overflow ⋯ → Tag menu). The session immediately appears under the group's section in the sidebar.
4. Use it — the group is a collapsible section with a count; click the chevron to fold or unfold it. Each group remembers open/collapsed per project.

Behavior worth knowing

• A group is a label, not a folder (an overlay). Putting a session in a group does NOT remove it from its normal status section — a running session you tag "Client X" still shows under Live, and also under Client X. Nothing ever disappears from where you expect it.
• Global vs. per-project scope. A global group's section appears in every project's sidebar (showing that project's tagged sessions); a project-scoped group's section appears only when one of its projects is selected.
• Empty groups hide themselves. A group with no sessions in the project you're viewing simply doesn't show a section there — so a global group only appears where it actually has members.
• A session can be in several groups. It then appears under each of them (tags cap at 10 per session, so a session can be in up to 10 groups).
• Off by default. The whole thing is gated behind the tag opt-in; a fresh install shows no groups until you enable tags AND flag a tag "Show as a sidebar group."
• Desktop and mobile. Group sections render in both the desktop sidebar and the mobile session list.

For agents

Under the hood (for agents)

• A group = a library tag with show_in_sidebar = 1 (an additive column on the tags table). The flag rides on the existing TAG_CREATE / TAG_UPDATE paths (and their CLI routes) — no new IPC channel.
• Membership is the existing session_tags join, surfaced per promoted tag via the existing TAGS_SESSIONS_FOR_TAG reverse lookup and intersected with the current project's sessions.
• Scope resolves from tag_project_scopes exactly like any tag (no rows = global).
• Rendering reuses the shared CollapsibleSessionSection + SessionRowList; the derivation is the pure deriveSessionGroups (src/renderer/src/lib/session-host/session-groups.ts), shared by desktop and mobile through the useSidebarGroups hook. The built-in status sections are untouched (groups are an independent overlay stack).
• Contract: .claude/memory/contracts/session-groups-contract.md (invariants G1–G7).

Status: opt-in (part of the tag feature; sessionTagsEnabled, off by default).

Related

The tag system a group is built on — creating tags, colors, scope rules, and the deletion cascade — is on the tag manager page; the free-form per-session tags that coexist with library tags are on the session tags page; and how the sidebar as a whole is arranged is on the projects sidebar page.