Sessions

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 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: 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)

​

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): This works from anywhere in the app — you don’t need to focus the terminal first. It clears the active session’s scrollback.

​

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.