Multi-Agent Setup

Configure CLEO for concurrent LLM agent coordination

Multi-Agent Setup

CLEO supports multiple AI agents working simultaneously on different parts of your project. This guide covers configuration and coordination patterns.

When to Use Multi-Agent

Large Projects

Multiple epics that can progress independently

Specialized Agents

Different agents for research, implementation, testing

Parallel Workflows

Teams needing concurrent work streams

Phase-Based Work

Different agents per project phase

Enabling Multi-Session Mode

cleo config set multiSession.enabled true
cleo config set multiSession.maxConcurrentSessions 5

Configuration Options

Option	Default	Description
multiSession.enabled	false	Enable multi-session support
multiSession.maxConcurrentSessions	5	Max simultaneous sessions
multiSession.maxActiveTasksPerScope	1	Active tasks per scope
multiSession.scopeValidation	strict	Overlap detection mode
multiSession.allowScopeOverlap	false	Allow overlapping scopes

Starting Concurrent Sessions

Agent 1: Auth Epic

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

Agent 2: UI Epic

cleo session start \
  --scope epic:T050 \
  --name "UI Components" \
  --agent claude-opus-2 \
  --auto-focus

Agent 3: Testing

cleo session start \
  --scope epicPhase --root T001 --phase testing \
  --name "Auth Tests" \
  --agent claude-sonnet-1 \
  --auto-focus

Scope Isolation

Each session operates within its defined scope:

Sessions cannot claim the same task simultaneously. Attempting to focus on a task claimed by another session returns an error.

Managing Sessions

# List all sessions
cleo session list

# List active sessions
cleo session list --status active

# Show sessions touching an epic
cleo session list --scope T001

# Show session details
cleo session show <session-id>

# Switch which session this terminal uses
cleo session switch <session-id>

Conflict Resolution

When scopes might overlap:

Strict Mode (Default)

cleo config set multiSession.scopeValidation strict

• Sessions cannot overlap at all
• Error returned if scope conflict detected
• Safest for avoiding conflicts

Relaxed Mode

cleo config set multiSession.allowScopeOverlap true

• Scopes can overlap
• First session to focus a task “wins”
• Requires more coordination discipline

Agent Identification

Track which agent owns which session:

# Start with agent identifier
cleo session start --agent opus-1 --scope epic:T001

# View sessions by agent
cleo session list --format json | jq '.[] | select(.agent == "opus-1")'

Best Practices

1. Plan Scope Boundaries

   Design non-overlapping scopes before starting sessions

2. Use Phase Scoping

   Separate agents by phase (one for core, one for testing)

3. Name Sessions Meaningfully

   Use --name for clarity in session listings

4. Monitor Session Health

   Check cleo session list regularly

Handoff Patterns

When one agent completes work that unblocks another:

# Agent 1 completes core work
cleo complete T005
cleo session end --note "Core implementation complete, ready for testing"

# Agent 2 sees dependency resolved
cleo session list  # Check status
cleo focus set T008  # Testing task now unblocked

Related

Orchestrator

Automated multi-agent coordination

Sessions Guide

Basic session management