Session groups
By default, the sidebar puts each session under its project. A group lets you keep related work together when it spans more than one folder. For example, you can keep a backend repo and a frontend repo together when you change both for the same feature.
A group can hold whole projects and single sessions. Groups show in a Groups section above the Projects section. In the All sessions view, the section below the groups is called Sessions.
Create a group
Section titled “Create a group”Use one of these methods:
- Drag a session or a project onto another session or project that is not in a group. Claude Code Kanban makes a new group that holds both.
- Right-click a session card or a project header and choose + New group…. On a touch screen, press and hold for about half a second to open the same menu. With the keyboard, move the sidebar cursor to the item and press Shift+F10 or the Menu key.
The name field of the new group opens in place. Type a name and press Enter.
The same menu also lists your other groups, so you can move an item to one of them. If the item is already in a group, the menu has a Remove from entry for that group.
Manage a group
Section titled “Manage a group”The group header has these controls:
- New session (the + button) opens the New session dialog for the group. See Start a session in a group. The button shows when the embedded terminal is on.
- Scratchpad opens a note for the group. See Session log and details.
- Rename (pencil icon) opens the name field in place.
- Delete (trash icon, or Ctrl+D with the sidebar cursor on the group header) removes the group after you confirm. Its sessions and projects go back to Projects.
To change the order of groups, drag a group header onto another group header.
To take an item out of a group, drag it onto the Projects or Sessions section label.
A group with no items shows the hint “Drop a session or a project here”. When a filter is on, an empty group does not show.
Start a session in a group
Section titled “Start a session in a group”The New session dialog has a Group field when you have one group or more. It starts at No group. Select a group there to start the session in it.
Select + on the group header to open the dialog with that group selected and the folder of the group’s most recent session. When the group has no sessions, the folder is the group’s first project.
The session joins the group when it starts, and its card shows there at once.
Where groups are saved
Section titled “Where groups are saved”The server saves your groups in <config-dir>/.cck/groups.json, so every browser and window on the board shows the same groups, and a change in one shows in the others at once. Each Claude config dir has its own groups, so groups you make for one config dir do not show for another.
Older versions kept groups in the browser’s local storage, under the key sessionGroups. The first board that loads after the upgrade moves its groups to the server one time and then sets the groupsMigratedAt key, so it does not move them again. A browser that loads later shows the server’s groups; its own older groups stay in sessionGroups but do not show.
Groups hold references to sessions and projects. A session that the sidebar filter hides stays in its group.
Groups from dispatch
Section titled “Groups from dispatch”When a session starts another session with dispatch start --group <group>, the started session joins that group. <group> is a group name, a path such as auth-refactor/api, or a group id. See Dispatch tasks to other sessions.
- When the group exists, the session joins it, and the group stays as it is.
- When it does not exist, the board makes it, and the missing groups of the path, as temporary groups. The name of a temporary group shows dimmed, with a Keep button on its header.
- The starting session stays where it is.
A temporary group goes when the Active view shows none of its sessions: they ended, or you dismissed them. A session that still starts counts as shown. The board checks this only on the full Active list, so a search, a project filter or another view does not remove a group.
To keep a temporary group, select Keep on its header, rename it, or move a session or project into it. It is then a group like any other. group create --transient makes a temporary group from the CLI.
Where a started session goes
Section titled “Where a started session goes”Claude Code Kanban picks the place for a started session when it starts, so the card does not move after it shows. A session started with --group goes to that group. A session started with --child shows under the starting session’s card, also when that card is in a group. A child does not join the group, so it does not keep a temporary group alive.
Until the first transcript line arrives, the board shows a “starting” placeholder card in that place.