Overview Maestro’s message queue system ensures commands execute sequentially per agent, preventing file conflicts and maintaining state consistency.
The queue automatically manages concurrent operations, so you can send multiple commands without worrying about conflicts.
Queue Architecture Per-Agent Isolation Each agent maintains its own execution queue:
interface Session { id : string executionQueue : QueuedItem [] state : 'ready' | 'busy' | 'connecting' | 'error' }
Benefits:
Parallel Execution - Different agents run concurrentlySequential Safety - Same agent processes one command at a timeNo File Conflicts - Agent workspace locked during execution
Queue Items interface QueuedItem { id : string // Unique identifier type : 'message' | 'command' // Item type text ?: string // Message content command ?: string // Command to execute commandDescription ?: string // Command description images ?: string [] // Attached images timestamp : number // When queued tabName ?: string // Source tab }
Queue Behavior When Commands Queue Commands queue when the agent is busy:
✅ Command executes immediately agent . state === 'ready' // Execute now, queue remains empty
⏳ Command queues for later agent . state === 'busy' // Add to queue, execute when ready executionQueue . push ( newItem )
Queue Processing
Command Received
User sends message or executes command
Check Agent State
If ready → execute immediately If busy → add to queue
Command Executes
Agent processes the command
Completion
Agent returns to ready state
Next Item
If queue not empty, process next item
Queue Indicators Visual Feedback The UI shows queue status:
// Execution queue indicator badge { executionQueue . length > 0 && ( < span className = "queue-badge" > {executionQueue. length } </ span > )}
Queue Browser View and manage queued items:
Open Browser
Browser Features
// Keyboard shortcut or button click onOpenExecutionQueueBrowser () // Shows: - All queued items across agents - Current vs global view - Drag - and - drop reordering
Queue Management Reordering Drag and drop to change execution order:
// Reorder within same agent only const handleReorder = ( sessionId : string , fromIndex : number , toIndex : number ) => { const queue = [ ... session . executionQueue ] const [ item ] = queue . splice ( fromIndex , 1 ) queue . splice ( toIndex , 0 , item ) updateSession ({ ... session , executionQueue: queue }) }
Items can only be reordered within the same agent’s queue. Cross-agent moves are not supported.
Removing Items Cancel queued commands:
// Remove specific item const handleRemove = ( sessionId : string , itemId : string ) => { const queue = session . executionQueue . filter ( item => item . id !== itemId ) updateSession ({ ... session , executionQueue: queue }) } // Clear all queued items const clearQueue = ( sessionId : string ) => { updateSession ({ ... session , executionQueue: [] }) }
View Modes Show queue for active agent only viewMode : 'current' filteredSessions = sessions . filter ( s => s . id === activeSessionId )
Show queues for all agents viewMode : 'global' filteredSessions = sessions . filter ( s => s . executionQueue . length > 0 )
Integration Points Group Chat Group chat messages queue when moderator/agents are busy:
// Group chat input onSend = {( content , images , readOnly) => { if ( groupChatState === 'busy' ) { // Queue for all participants participants . forEach ( p => { queueMessage ( p . sessionId , content , images ) }) } else { // Execute immediately sendMessage ( content , images , readOnly ) } }}
Auto Run Batch processing locks agent and prevents queueing:
// During Auto Run batch if ( batchRunState . isRunning && ! batchRunState . worktreeActive ) { // Agent locked, UI disabled // Queue not available for this agent isLocked = true }
Auto Run without worktrees locks the agent completely. Use worktrees for parallel work.
Slash Commands Slash commands queue like regular messages:
interface QueuedItem { type : 'command' command : '/fix-typescript' // Slash command commandDescription : 'Fix TS errors' // Display description tabName : 'Main' // Source tab timestamp : 1234567890 }
Offline Queue (Mobile) Mobile interface supports offline queueing:
interface OfflineQueueItem { sessionId : string message : string timestamp : number status : 'pending' | 'sending' | 'sent' | 'error' } // Commands queue locally when offline // Auto-send when connection restored
Sync Behavior
Offline Command
User sends message while offline
Local Queue
Message queues in browser storage
Connection Restored
WebSocket reconnects to desktop
Sync
Queued messages sent to desktop queue
Execution
Desktop processes normally
Queue Limits Large queues can impact performance. Consider:
Maximum queue size per agent
Time-based item expiration
User warnings for long queues
// Example limits (not currently enforced) const MAX_QUEUE_SIZE = 50 const QUEUE_ITEM_TTL = 30 * 60 * 1000 // 30 minutes if ( executionQueue . length >= MAX_QUEUE_SIZE ) { showWarning ( 'Queue is full. Please wait for items to process.' ) }
Memory Usage Queue items with images consume memory:
// Image data stored as base64 data URLs interface QueuedItem { images ?: string [] // Full base64 encoded images } // Consider: // - Limit image count per item // - Compress images before queueing // - Clear processed items immediately
Debugging Queue Inspector View queue state in dev tools:
// Global debug helper window . inspectQueue = ( sessionId : string ) => { const session = sessions . find ( s => s . id === sessionId ) console . table ( session ?. executionQueue . map ( item => ({ type: item . type , preview: item . text ?. slice ( 0 , 50 ) || item . command , images: item . images ?. length || 0 , age: Date . now () - item . timestamp }))) }
Event Logging // Queue events for debugging const queueLogger = { onEnqueue : ( sessionId , item ) => { console . log ( `[Queue] Enqueued ${ item . type } for ${ sessionId } ` , item ) }, onDequeue : ( sessionId , item ) => { console . log ( `[Queue] Dequeued ${ item . type } for ${ sessionId } ` , item ) }, onReorder : ( sessionId , from , to ) => { console . log ( `[Queue] Reordered ${ sessionId } items: ${ from } → ${ to } ` ) } }
Best Practices For Users
Monitor Queue Length - Check queue badge before sending many commandsUse Worktrees - Enable worktrees for Auto Run to allow parallel workPrioritize - Reorder queue items to prioritize urgent commandsClear Stale Items - Remove old queued items you no longer need
For Developers
Always Check State - Check agent state before executing commandsHandle Queue Events - Listen for queue changes to update UIProvide Feedback - Show clear queue indicators in UITest Edge Cases - Test with full queues, offline mode, errors