Session Management

Learn session protocols, focus management, and work continuity patterns

Session Management

CLEO sessions provide structure for work continuity across terminal sessions and Claude conversations. This guide covers session protocols and focus management.

Core Concepts

Sessions Persist

Sessions survive terminal and Claude conversation boundaries. Resume where you left off.

Sessions Coexist

Multiple sessions can be active simultaneously on different scopes. No need to suspend.

One Active Task

Each session enforces single-task focus within its scope for clarity.

Audit Trail

Every operation is logged for complete traceability and recovery.

Session Lifecycle

Starting a Session

Basic

cleo session start

With Scope

# Work on specific epic
cleo session start --scope epic:T001

# Work on task group
cleo session start --scope taskGroup:T005

# Phase-filtered scope
cleo session start --scope epicPhase --root T001 --phase testing

Named Session

cleo session start \
  --scope epic:T001 \
  --name "Auth Implementation" \
  --agent opus-1 \
  --auto-focus

During a Session

# Set your current task
cleo focus set T001

# Add progress notes
cleo focus note "Implementing JWT validation"

# View current focus
cleo focus show

# Complete and move on
cleo complete T001
cleo focus set T002

Ending a Session

End Session

cleo session end --note "Completed auth middleware"

Focus Management

CLEO enforces single-task discipline - only one task active at a time within a session scope.

Why Single-Task Focus?

Single-task focus prevents context switching overhead and provides clarity on current work. It’s the foundation of CLEO’s anti-hallucination design.

Focus Commands

# Set active task
cleo focus set T001

# View current focus
cleo focus show

# Clear focus
cleo focus clear

# Add session-level progress note
cleo focus note "Making progress on validation logic"

# Suggest next action
cleo focus next "Write unit tests for validator"

Focus vs Task Notes

Command	Purpose	Storage
cleo focus note "..."	Session-level progress	.focus.sessionNote (replaces)
cleo update T001 --notes "..."	Task-specific notes	Task’s notes array (appends)

Session States

State	Meaning	Resumable
active	Currently working	N/A
suspended	Paused (explicit)	Yes
ended	Work complete for now	Yes
closed	Permanently archived	No

Multi-Session Workflows

Multiple sessions can run concurrently on different scopes:

# Terminal 1: Auth work
cleo session start --scope epic:T001 --name "Auth"

# Terminal 2: UI work (NO CONFLICT - different scope)
cleo session start --scope epic:T050 --name "UI"

# List all active sessions
cleo session list --status active

Scope Types

Type	Definition	Example
task	Single task only	--scope task:T005
taskGroup	Parent + direct children	--scope taskGroup:T005
subtree	Parent + all descendants	--scope subtree:T001
epicPhase	Epic filtered by phase	--scope epicPhase --root T001 --phase testing
epic	Full epic tree	--scope epic:T001

Session Binding

When you start or resume a session, CLEO binds that terminal to the session:

# Start session - binds this terminal
cleo session start --scope epic:T001

# All commands now use this session context
cleo focus show      # Shows THIS session's focus
cleo focus set T005  # Sets focus within THIS scope

# Switch to different session
cleo session switch <session-id>

Daily Workflow Pattern

1. Morning: Check State

   cleo session list
   cleo dash
   cleo focus show
   
2. Resume or Start

   # Resume existing session
   cleo session resume <session-id>
   
   # Or start new session
   cleo session start --scope epic:T001 --auto-focus
   
3. Work: Task Cycle

   cleo focus set T001
   # ... do work ...
   cleo update T001 --notes "Completed validation"
   cleo complete T001
   cleo next  # Suggests next task
   cleo focus set T002
   
4. Evening: Clean Up

   cleo complete T002
   cleo archive
   cleo session end --note "Completed auth tasks"
   

Resume Patterns

# Resume by session ID
cleo session resume abc123

# Resume most recent session
cleo session resume --last

# Resume most recent for specific scope
cleo session resume --last --scope epic:T001

# View session details before resuming
cleo session show abc123

Error Recovery

Multiple Active Tasks

# Reset focus to correct task
cleo focus set T001
# This clears other active tasks in scope

Orphaned Session

# Check session status
cleo session status

# Force end if stuck
cleo session end --force

Scope Conflict

# Check scope availability
cleo session list --scope T001

# Use disjoint scopes
cleo session start --scope epicPhase --root T001 --phase testing
cleo session start --scope epicPhase --root T001 --phase polish

Next Steps

Context Monitoring

Track context window usage

Multi-Agent Setup

Configure for multiple AI agents