Create, switch, and manage sessions
A session is one conversation with a role. Create it with a role, model, and thinking level; then switch from the left sidebar or search by title within the workspace. Running sessions show their state clearly.
Create a session
Section titled “Create a session”-
Choose an entry point
Section titled “Choose an entry point”Expand a workspace and click + next to the Sessions heading, or click “New session” in the center. Both open the same dialog.
-
Pick a role
Section titled “Pick a role”The list comes from Settings → Roles and starts on Orchestrator. Choose Worker when one agent should work directly, or pick a custom role.
-
Pick a model and thinking level
Section titled “Pick a model and thinking level”The model select is grouped by provider. If the model supports reasoning, thinking levels appear below; otherwise the dialog explains what is missing.
-
Click Create
Section titled “Click Create”The new session is selected automatically, appears in the sidebar, and opens in the chat view. If no provider is available, add one under Settings → Model providers first.
Switch and search
Section titled “Switch and search”Expand a workspace and click a session row to switch. The center header shows the status dot, title, role badge, and current branch; the status bar shows tokens, cost, approval mode, branch, and model.
Shortcuts: Ctrl+Shift+[ for the previous session, Ctrl+Shift+] for the next, and Ctrl+K for session search. Use ⌘ instead of Ctrl on macOS.
Status and limits
Section titled “Status and limits”| Status | Meaning | What you can do |
|---|---|---|
| Idle | The current turn has settled | Keep typing, switch models, archive, or delete |
| Running | The agent is working on this turn | Messages queue; stop is available; model switch, archive, and delete are blocked |
| Waiting for approval | A tool call needs your confirmation | Use the approval bar above the composer; the related task is paused |
| Error | A turn or record read failed | Read the notice above the timeline, fix the cause, and send again |
Switching models while running is refused; wait for the turn to settle. Archiving and deleting also wait for the turn to finish.
View worker sessions
Section titled “View worker sessions”After a dispatch, the worker session is registered in the same workspace’s session list and carries a Worker role badge. Open it to inspect its task, messages, and tool calls; task-level output, attempts, and diffs live in the task details under Tasks on the right.
To adjust the work, describe the change in the orchestrator’s session so the brief, review, and merge stay consistent.
Archive and delete
Section titled “Archive and delete”Hover a session row to reveal archive and delete. Archived sessions move into the collapsible “Archived” group at the bottom and can be restored. Deleting removes the session from the list while keeping the underlying record; both actions are blocked while a session runs.
Under Settings → General → Sessions you can archive idle sessions after a number of days, clean up merged and clean worktrees on archive, and delete archived records after a number of days.