Sessions are the core of AgentOS. Each session is a terminal running an AI coding assistant like Claude Code, Codex, or Aider.

Creating Sessions

Click + New Session in the sidebar:

Select agent - Claude Code, Codex, Aider, etc.
Choose directory - Browse and select your project folder
Optional settings:
- Assign to a project
- Enable git worktree for isolated branch
- Set a custom system prompt
- Choose a specific model

Quick Create

For faster session creation:

Double-click a project to create a session with that project's defaults
Use the quick switcher (Cmd+K) and type "new" to create a session

Session Status

AgentOS monitors sessions in real-time and detects their status:

Status	Indicator	Meaning
Running	Green	Agent is actively working
Waiting	Yellow	Needs your input (approval, Y/n prompt)
Idle	Gray	No recent activity
Dead	Red	tmux session no longer exists

How Status Detection Works

AgentOS scans terminal output for:

Waiting patterns - [Y/n], approval prompts, "Continue?" questions
Busy indicators - "thinking", spinners, "esc to interrupt"
Activity spikes - Distinguishes bursts from sustained work

A 2-second cooldown prevents false "idle" detection when agents pause briefly.

Notifications

Get alerted when sessions need attention:

Click the bell icon in the header
Enable browser notifications
Choose to enable sounds (optional)

You'll receive a notification whenever any session enters "waiting" status. On mobile, this works even when AgentOS isn't the active tab.

Resume & Fork (Claude Code)

Claude Code sessions support two unique features:

Resume

Pick up exactly where you left off:

Click the session menu (⋮ or long-press on mobile)
Select Resume
Claude continues with full conversation history

AgentOS auto-detects Claude session IDs from ~/.claude/projects/, so resume works even after server restarts.

Fork

Branch a conversation to explore alternatives:

Click the session menu
Select Fork
A new session starts with the same conversation context

Both sessions continue independently. Great for:

A/B testing different approaches
Exploring a risky change without losing the stable version
Letting an agent continue while you try something manually

Multi-Pane Layout

Desktop

Run up to 4 sessions side-by-side:

Drag the dividers to resize panes
Each pane can have multiple tabs
Click a session to open in current pane
Cmd/Ctrl+click to open in a new pane

Mobile

Single-pane view with quick switching:

Bottom tab bar shows 3 recent sessions
Tap to switch instantly
Swipe from left edge to open full session list

Tabs

Each pane supports tabbed sessions:

Click session - Opens in current pane's tabs
Click tab X - Close that tab
Drag tabs - Reorder within pane

Tabs let you keep multiple sessions ready without using multiple panes.

Session Groups

Organize sessions into collapsible folders:

Right-click a session (long-press on mobile)
Select Move to Group
Create a new group or select existing

Groups appear nested under projects:

📁 My Project
   📂 Features
      └─ Auth module
      └─ Dashboard
   📂 Bug fixes
      └─ Fix #123

Click group headers to collapse/expand.

Bulk Operations

Select multiple sessions for batch actions:

Selection

Shift+click - Select a range
Cmd/Ctrl+click - Toggle individual sessions
Long-press (mobile) - Enter selection mode

Actions

With sessions selected:

Delete Selected - Remove all selected sessions
Move to Project - Batch reassign
Move to Group - Batch organize

Session Menu

Access session actions via the menu (⋮ button or long-press):

Action	Description
Resume	Continue Claude session (Claude only)
Fork	Branch conversation (Claude only)
Rename	Change session name
Move to Project	Reassign to different project
Move to Group	Organize into group
Create PR	Open PR for worktree branch
Kill Session	Terminate the tmux session
Delete	Remove from AgentOS

Session Persistence

Sessions persist across:

Browser refreshes - Just reload, session keeps running
Server restarts - tmux maintains sessions independently
Device switches - Start on desktop, continue on phone

This is possible because each session runs in a tmux session (claude-{uuid}, codex-{uuid}, etc.) that lives independently of the web UI.

Importing Existing Sessions

If you have Claude Code or other agents already running in tmux, AgentOS can import them:

Sessions matching the pattern {agent}-{uuid} appear automatically
Or manually add sessions via the import feature

Session Data

Each session tracks:

Name - Display name (editable)
Agent type - Claude Code, Codex, etc.
Working directory - Project path
Status - Running, waiting, idle
Claude session ID - For resume/fork (Claude only)
Worktree info - Branch, port, PR status
Parent session - If spawned by a conductor
Timestamps - Created, last activity

This data persists in SQLite and enables features like status detection and conversation resume.