# 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
