> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clideck.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Create, manage, resume, and organize your terminal sessions

Sessions are the core of CliDeck. Each session is a real terminal running a CLI agent or shell command.

## Creating a Session

Click the **+** button in the sidebar to open the session launcher. You'll see:

* **Agent buttons** — One for each enabled agent (Claude Code, Codex, Gemini CLI, OpenCode), ordered by most recently used
* **Shell** — A plain terminal, always listed last
* **Session name** — Optional. CliDeck generates a random name if you leave it blank
* **Working directory** — Defaults to your configured default path. Click **Browse** to pick a different folder
* **Project** — Optionally assign the session to a project right away
* **Role** — Optionally assign a role to the session. When selected, the session name auto-fills with the role name. The role's instructions are injected into the agent after it starts.

Click an agent button to launch the session immediately.

## The Session Sidebar

Each session appears in the sidebar with:

| Element          | What It Shows                                   |
| ---------------- | ----------------------------------------------- |
| Agent icon       | Which agent is running                          |
| Session name     | Editable — double-click to rename               |
| Status indicator | Green bounce = working, "zzZ" = idle            |
| Preview text     | Latest meaningful output line from the agent    |
| Time             | How long since last activity                    |
| Unread dot       | Blue dot if there's new output you haven't seen |

Click a session to switch to it. The terminal appears in the main area with full keyboard focus.

## Renaming Sessions

Double-click the session name in the sidebar to edit it. Press **Enter** to save or **Escape** to cancel.

## Session Resume

When CliDeck shuts down (or you close the app), sessions from agents that support resume are automatically saved to `sessions.json`. Next time you start CliDeck, these appear in a **Previous Sessions** section at the bottom of the sidebar.

Click the resume button on any saved session to pick up where you left off. CliDeck uses the agent's resume command (e.g., `claude --resume <id>`) to reconnect.

Resume requires:

* The agent supports resume (Claude Code, Codex, Gemini CLI, OpenCode all do)
* A session ID was captured during the original session (via telemetry or plugin)

<Note>
  If CliDeck is killed forcefully (e.g., `kill -9`), sessions may not be saved. Normal shutdown (Ctrl+C or closing the terminal) saves sessions correctly.
</Note>

## Restarting Sessions

Sometimes you need to restart a session — for example, after changing the terminal theme polarity (switching from a dark theme to a light theme). CliDeck shows a restart banner when this is needed.

A restart kills the current terminal process and launches a new one. If the agent supports resume and has a session ID, the restart uses the resume command so you don't lose context.

## Muting Sessions

Right-click a session (or click the menu button) and select **Mute** to disable notifications for that session. A muted session still shows status changes in the sidebar, but won't trigger browser notifications or sounds.

## Clearing the Terminal

To clear a terminal's scrollback buffer (visual clear, like macOS Terminal's Cmd+K):

| Platform        | Shortcut         |
| --------------- | ---------------- |
| macOS           | **Cmd+K**        |
| Windows / Linux | **Ctrl+Shift+K** |

This works from anywhere in the app — you don't need to focus the terminal first. It clears the active session's scrollback.

<Note>
  On macOS, Cmd and Ctrl are separate modifiers. CliDeck only captures Cmd+K — it does not interfere with Ctrl+K (kill-line) or other Ctrl keybindings that CLI agents use.
</Note>

## Closing Sessions

Right-click a session and select **Delete**, or use the session context menu. If close confirmation is enabled in settings, you'll see a confirmation dialog before the session is closed.

Closing a session kills the terminal process. If the agent supports resume, the session is saved for later resume.