---
title: Custom Session Groups (create your own collapsible sidebar sections)
---

# 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](tag-manager.md) page; the free-form per-session tags that
coexist with library tags are on the [session tags](session-tags.md) page; and how the sidebar
as a whole is arranged is on the [projects sidebar](projects-sidebar.md) page.