Multi-Agent Coordination

Parallel AI agents working together on complex tasks

Overview

CLIO supports spawning multiple AI agents that work in parallel on the same codebase without conflicts. This enables:

• Parallel task execution
• File locking to prevent concurrent edits
• Git coordination for safe commits
• Knowledge sharing between agents
• Message-based communication

Operating Modes

Oneshot Mode (Default)

Agent spawns, executes a single task, and exits:

: /subagent spawn "fix bug in Module::A"

Best for: Independent parallel tasks that don't need coordination

Persistent Mode

Agent stays alive, polls for messages, handles multiple tasks:

: /subagent spawn "refactor auth module" --persistent

Best for: Complex work requiring back-and-forth communication

Usage Examples

Spawning Agents

# Basic spawn
: /subagent spawn "add tests for UserController"

# Persistent agent
: /subagent spawn "refactor database layer" --persistent

# Specify model
: /subagent spawn "optimize queries" --model gpt-4o --persistent

Communication

# View messages from agents
: /subagent inbox

# Reply to agent question
: /subagent reply agent-1 "yes, proceed with that approach"

# Send guidance
: /subagent send agent-2 "try alternative implementation"

# Broadcast to all agents
: /subagent broadcast "code freeze - finish current work"

Monitoring

# List all active agents
: /subagent list

# Show detailed status
: /subagent status agent-1

# View file/git locks
: /subagent locks

# See shared discoveries
: /subagent discoveries

Message Types

From Agents

Type	Color	Meaning
question	Yellow	Agent needs guidance
blocked	Red	Waiting for input
complete	Green	Task finished
status	Cyan	Progress update
discovery	Magenta	Shared finding

Coordination Features

• File Locking: Only one agent can edit a file at a time
• Git Coordination: Commits are serialized to avoid conflicts
• Discovery Sharing: Agents share findings with each other
• Automatic Inbox Polling: Main session checks for new messages

Best Practices

• Use oneshot mode for independent tasks
• Use persistent mode when agents need to ask questions
• Monitor the inbox regularly
• Broadcast important context to all agents
• Use discoveries to share findings across agents

Next Steps

• Remote Execution - Run CLIO on remote systems
• Workflows - Effective usage patterns
• Tools Reference - All available tools