Sessions
Manage your AI coding conversations across projects.
What are Sessions?
Sessions are individual conversations with the AI. Each session tracks messages, tool calls, file changes, and context. Sessions are organized by project and can be highlighted, forked, or filtered.
Sessions List
The Sessions screen shows all your conversations organized by project and time.
Header
- Sessions title - Large header text
- Refresh button - Manually refresh the list
- Connection dot - Green (connected) or red (disconnected)
- Subtitle - "Continue your AI coding sessions"
Filter Controls
Below the header, you'll find filter options:
- Project filter - Chip showing "All projects" or selected project name
- Background tasks toggle - Tree icon with count of subagent tasks
- Title filters - Hide sessions matching text patterns or regex
Session Cards
Each session card displays:
| Element | Description |
|---|---|
| Avatar | First letter of session title |
| Status Dot | Bottom-left indicator (active/idle) |
| Title | Session name (auto-generated or custom) |
| Project + Time | "ProjectName - 2h ago" |
| Forked Badge | Purple "Forked" pill if branched |
| Child Count | Tree icon with number if has background tasks |
Session States
Sessions can be in different states indicated visually:
| Status | Visual Indicator | Description |
|---|---|---|
| Idle | Gray dot, no badge | Session is not actively running |
| Active | Blue pulsing dot, "Active" badge | AI is currently responding |
| Retry | Yellow dot, "Retry" badge | Session is retrying after error |
| Highlighted | Gold star, colored border | Starred by user for quick access |
Active Sessions
Running sessions appear at the top in a special section:
- Pulsing indicator - Animated dot for active sessions
- Active badge - Blue pill showing session is working
- Retry badge - Yellow pill if retrying after error
Highlighted Sessions
Sessions you've starred appear in a separate "Highlighted" section:
- Star icon - Gold star on the card
- Accent border - Colored left border
- Priority placement - Always visible above regular sessions
To highlight a session
Long-press on any session card and select "Highlight" from the menu.
Session Actions
| Action | How to Trigger | Result |
|---|---|---|
| Open | Tap the card | Opens session in Chat screen |
| Highlight | Long press > Highlight | Toggle starred status |
| Rename | Long press > Rename | Change session title |
| Delete | Swipe left | Delete with confirmation dialog |
Background Tasks
When "Background Tasks" toggle is enabled, sessions with subagent work show expandable children:
- Sessions with children show an expand arrow
- Tap the child count badge to expand
- Nested cards appear indented below the parent
- Each child shows: Agent badge (e.g., "@explore"), task description, status
Forking Sessions
Fork a session to create a branch from any point in the conversation:
- Use the menu option in Chat screen
- Or long-press a message and select "Fork from here"
- Forked sessions show a purple "Forked" badge
- Great for trying alternative approaches without losing context
Empty State
When no sessions exist, you'll see:
- Chat icon - Indicates no sessions
- Message - Prompt to create a new session from Projects