Skip to content

3.4-sessions.md

Latest commit

 

History

History
149 lines (99 loc) · 5.2 KB

3.4-sessions.md

File metadata and controls

149 lines (99 loc) · 5.2 KB
Raw

3.4 Session Manager

The Session Manager lets you browse, search, and manage conversation sessions from all supported CLI tools in one place.

Supported Applications

Application Session Storage Location
Claude Code ~/.cache/claude/projects/*.jsonl
Codex Codex config sessions directory
OpenCode ~/.local/share/opencode/ (JSON or SQLite)
OpenClaw ~/.openclaw/agents/<agent>/sessions/*.jsonl
Gemini CLI ~/.cache/gemini/tmp/<project_hash>/chats/
Hermes ~/.hermes/state.db or ~/.hermes/sessions/*.jsonl

Opening the Session Manager

Click the Sessions button in the main navigation bar toolbar.

Note: The Session Manager covers the six session sources listed above; the Claude Desktop entry reuses the Claude Code session view.

Interface Layout

The Session Manager uses a two-column layout:

  • Left panel: Session list with search and filter toolbar
  • Right panel: Selected session details with conversation history

Session List (Left Panel)

Each session entry displays:

  • Provider icon
  • Session title
  • Last active time (relative format, e.g., "5 min ago")

Session Details (Right Panel)

When a session is selected, the right panel shows:

  • Title: Derived from session title, project directory name, or session ID
  • Last active date/time: Full timestamp
  • Project directory: Clickable to copy full path (shows basename with tooltip for full path)
  • Resume command: Displayed in monospace style when available
  • Conversation history: Full message transcript

Search & Filtering

Full-Text Search

Use the search box at the top of the left panel to search across:

  • Session ID
  • Title
  • Summary
  • Project directory
  • Source file path

The search supports prefix matching and filters results in real-time. Press Esc to clear the search.

Provider Filtering

Click the provider filter dropdown (top-right of left panel) to filter by application:

  • All — Show sessions from all providers
  • Claude Code
  • Codex
  • OpenCode
  • OpenClaw
  • Gemini CLI
  • Hermes

The filter can be combined with search.

Refresh

Click the refresh button (circular arrow icon) to re-scan all provider directories for new or deleted sessions.

Session Actions

Resume Session

Click the Resume button (play icon) on a selected session to continue the conversation.

On macOS:

  • CC Switch launches your preferred terminal with the resume command
  • The terminal opens in the session's project directory
  • If terminal launch fails, the command is copied to your clipboard instead

Supported terminals (macOS): Terminal.app, iTerm2, Ghostty, Kitty, WezTerm, Alacritty, Warp

On other platforms:

  • The resume command is copied to your clipboard
  • Paste it into your terminal to resume

The Resume button is disabled if the session has no resume command available.

Directory Picker (Claude Terminal Resume)

Starting from v3.13.0, Claude sessions show a directory picker before resume, allowing you to override the default project directory. Useful when:

  • Project was moved: The original project directory was moved or renamed
  • Broken symlink: The original path is no longer accessible
  • Temporary directory change: You want to continue the conversation in a different working directory

How to use:

  1. Click the Resume button on a Claude session
  2. In the popup directory picker, confirm the default directory or choose a new one
  3. CC Switch launches the Claude terminal session in the selected directory

Note: Codex / Gemini / OpenCode / OpenClaw / Hermes session resume flows do not yet include the directory picker and still use the session's original project directory.

Delete Session

Click the Delete button (trash icon) to permanently remove a session file. A confirmation dialog is shown before deletion.

Sessions without a local source path (e.g., immutable sessions) cannot be deleted.

Batch Operations

For managing multiple sessions at once:

  1. Click the Batch Mode button (checkbox icon) in the left panel toolbar
  2. Select sessions using the checkboxes that appear
  3. Use Select All to select all filtered results, or Clear to deselect
  4. Click Batch Delete (red trash icon) to delete all selected sessions

A confirmation dialog shows the count before deletion. Results report the number of successful deletions and any failures.

Conversation History

Message Display

Messages are color-coded by role:

  • User messages: Green, left-aligned
  • AI (Assistant) messages: Blue, right-aligned
  • System messages: Amber
  • Tool messages: Purple

Table of Contents

For longer conversations, a Table of Contents is available:

  • Desktop (XL+ screens): Sidebar on the right showing user message previews
  • Smaller screens: Floating button (list icon) at bottom-right that opens a dialog

Click any entry to scroll to that message, which is briefly highlighted.

Tips

  • Sessions are sorted by last activity time (newest first)
  • The session count badge updates as you search and filter
  • OpenCode sessions may come from both JSON files and SQLite database — duplicates are automatically deduplicated