Session Management

cc-deck tracks Claude Code sessions automatically. When you start Claude Code in a tab, the sidebar picks it up and displays it. This page covers the actions you can take on sessions: pause, rename, search, delete, and create new ones.

Pause

Pausing a session excludes it from the smart attend rotation. This is useful when you have sessions you want to keep open but do not need attention right now.

To pause a session:

  1. Enter navigation mode (Alt+s)

  2. Move to the session you want to pause (j/k)

  3. Press p

The paused session shows a ⏸ icon and its name appears dimmed. Press p again on a paused session to resume it.

Paused sessions are still visible in the sidebar and you can switch to them with Enter. They are simply excluded from the smart attend cycle.

Rename

By default, sessions are named after their working directory or git repository. Tabs with a single session are also auto-renamed to match. You can give sessions a custom name for easier identification.

To rename a session:

  1. Enter navigation mode (Alt+s)

  2. Move to the session (j/k)

  3. Press r

  4. Type the new name

  5. Press Enter to confirm or Esc to cancel

You can also right-click a session in the sidebar to start renaming.

Renamed sessions keep their custom name even when the working directory changes. The rename is persisted and survives tab switches and sidebar restarts.

Search

When you have many sessions open, search helps you find the one you need.

  1. Enter navigation mode (Alt+s)

  2. Press /

  3. Type a search term

  4. The sidebar filters to show only sessions whose name matches (case-insensitive substring)

  5. Press Enter to switch to the highlighted result, or Esc to clear the filter

Search matches against the session display name (custom name if renamed, or directory/git name).

Delete

To close a session and its tab:

  1. Enter navigation mode (Alt+s)

  2. Move to the session (j/k)

  3. Press d

This closes the tab containing the session. If the tab has unsaved work in Claude Code, Claude Code handles its own save prompts.

New Tab

Press n in navigation mode to open a new tab. The new tab is created from the configured tab template and you can start Claude Code in it manually.

cc-deck intentionally does not auto-start Claude Code in new tabs. You choose when and where to run it.

Session State Tracking

The sidebar tracks several states for each session:

State Display Meaning

Init

Dim

Session detected but Claude Code has not started yet

Idle

Normal

Claude Code is running but waiting for user input

Working

Animated

Claude Code is actively generating output or calling tools

Permission

Bold, highlighted

Claude Code needs permission to proceed (highest priority for attend)

Done

Checkmark

Claude Code finished its task

Paused

⏸ icon, dimmed

User paused this session

State changes are detected automatically via Claude Code hooks. You do not need to do anything to keep the sidebar updated.

Snapshots

Session state can be saved and restored using snapshots. This is managed through the CLI:

# Save current session state
cc-deck snapshot save my-checkpoint

# List saved snapshots
cc-deck snapshot list

# Restore a snapshot
cc-deck snapshot restore my-checkpoint

# Remove a snapshot
cc-deck snapshot remove my-checkpoint

Auto-save is enabled by default via hooks. Every time a Claude Code session completes a task, the state is saved automatically with a sequential name (snapshot-1, snapshot-2, etc.).