Claude-Code-Workflow/docs/features/queue.md

Queue Management

One-Liner

The Queue Management page provides centralized control over issue execution queues with scheduler controls, status monitoring, and session pool management.

---

Pain Points Solved

Pain Point	Current State	Queue Solution
Disorganized execution	No unified task queue	Centralized queue with grouped items
Unknown scheduler status	Can't tell if scheduler is running	Real-time status indicator (idle/running/paused)
No execution control	Can't start/stop queue processing	Start/Pause/Stop controls with confirmation
Concurrency limits	Too many simultaneous sessions	Configurable max concurrent sessions
No visibility	Don't know what's queued	Stats cards + item list with status tracking
Resource waste	Idle sessions consuming resources	Session pool overview with timeout config

---

Overview

Location: ccw/frontend/src/pages/QueuePage.tsx (legacy), ccw/frontend/src/components/terminal-dashboard/QueuePanel.tsx (current)

Purpose: View and manage issue execution queues with scheduler controls, progress tracking, and session pool management.

Access: Navigation → Issues → Queue tab OR Terminal Dashboard → Queue floating panel

Layout:

+--------------------------------------------------------------------------+
|  Queue Panel Header                                                        |
+--------------------------------------------------------------------------+
|  Scheduler Status Bar                                                       |
|  +----------------+  +-------------+  +-------------------------------+         |
|  | Status Badge   |  | Progress    |  | Concurrency (2/2)            |         |
|  +----------------+  +-------------+  +-------------------------------+         |
+--------------------------------------------------------------------------+
|  Scheduler Controls                                                          |
|  +--------+  +--------+  +--------+  +-----------+                      |
|  | Start  |  | Pause  |  | Stop   |  | Config    |                      |
|  +--------+  +--------+  +--------+  +-----------+                      |
+--------------------------------------------------------------------------+
|  Queue Items List                                                           |
|  +---------------------------------------------------------------------+    |
|  | QueueItemRow (status, issue_id, session_key, actions)              |    |
|  | - Status icon (pending/executing/completed/blocked/failed)         |    |
|  | - Issue ID / Item ID display                                        |    |
|  | - Session binding info                                              |    |
|  | - Progress indicator (for executing items)                          |    |
|  +---------------------------------------------------------------------+    |
|  | [More queue items...]                                               |    |
|  +---------------------------------------------------------------------+    |
+--------------------------------------------------------------------------+
|  Session Pool Overview (optional)                                           |
|  +--------------------------------------------------------------------------+
|  | Active Sessions | Idle Sessions | Total Sessions                      |
|  +--------------------------------------------------------------------------+

---

Live Demo

:::demo QueueManagementDemo #QueueManagementDemo.tsx :::

---

Core Features

Feature	Description
Scheduler Status	Real-time status indicator (idle/running/paused) with visual badge
Progress Tracking	Progress bar showing overall queue completion percentage
Start/Pause/Stop Controls	Control queue execution with confirmation dialog for stop action
Concurrency Display	Shows current active sessions vs max concurrent sessions
Queue Items List	Scrollable list of all queue items with status, issue ID, and session binding
Status Icons	Visual indicators for item status (pending/executing/completed/blocked/failed)
Session Pool	Overview of active, idle, and total sessions in the pool
Config Panel	Adjust max concurrent sessions and timeout settings
Empty State	Friendly message when queue is empty with instructions to add items

---

Component Hierarchy

QueuePage (legacy) / QueuePanel (current)
├── QueuePanelHeader
│   ├── Title
│   └── Tab Switcher (Queue | Orchestrator)
├── SchedulerBar (inline in QueueListColumn)
│   ├── Status Badge
│   ├── Progress + Concurrency
│   └── Control Buttons (Play/Pause/Stop)
├── QueueItemsList
│   └── QueueItemRow (repeating)
│       ├── Status Icon
│       ├── Issue ID / Item ID
│       ├── Session Binding
│       └── Progress (for executing items)
└── SchedulerPanel (standalone)
    ├── Status Section
    ├── Progress Bar
    ├── Control Buttons
    ├── Config Section
    │   ├── Max Concurrent Sessions
    │   ├── Session Idle Timeout
    │   └── Resume Key Binding Timeout
    └── Session Pool Overview

---

Props API

QueuePanel

Prop	Type	Default	Description
embedded	boolean	false	Whether panel is embedded in another component

SchedulerPanel

Prop	Type	Default	Description
-	-	-	This component accepts no props (all data from Zustand store)

QueueListColumn

Prop	Type	Default	Description
-	-	-	This component accepts no props (all data from Zustand store)

---

State Management

Zustand Stores

Store	Selector	Purpose
queueSchedulerStore	selectQueueSchedulerStatus	Current scheduler status (idle/running/paused)
queueSchedulerStore	selectSchedulerProgress	Overall queue completion percentage
queueSchedulerStore	selectQueueItems	List of all queue items
queueSchedulerStore	selectCurrentConcurrency	Active sessions count
queueSchedulerStore	selectSchedulerConfig	Scheduler configuration
queueSchedulerStore	selectSessionPool	Session pool overview
queueSchedulerStore	selectSchedulerError	Error message if any
issueQueueIntegrationStore	selectAssociationChain	Current association chain for highlighting
queueExecutionStore	selectByQueueItem	Execution data for queue item

Queue Item Status

type QueueItemStatus =
  | 'pending'      // Waiting to be executed
  | 'executing'    // Currently being processed
  | 'completed'    // Finished successfully
  | 'blocked'      // Blocked by dependency
  | 'failed';      // Failed with error

Scheduler Status

type QueueSchedulerStatus =
  | 'idle'     // No items or stopped
  | 'running'  // Actively processing items
  | 'paused';  // Temporarily paused

---

Usage Examples

Basic Queue Panel

import { QueuePanel } from '@/components/terminal-dashboard/QueuePanel'

function QueueSection() {
  return <QueuePanel />
}

Standalone Scheduler Panel

import { SchedulerPanel } from '@/components/terminal-dashboard/SchedulerPanel'

function SchedulerControls() {
  return <SchedulerPanel />
}

Queue List Column (Embedded)

import { QueueListColumn } from '@/components/terminal-dashboard/QueueListColumn'

function EmbeddedQueue() {
  return <QueueListColumn />
}

Queue Store Actions

import { useQueueSchedulerStore } from '@/stores/queueSchedulerStore'

function QueueActions() {
  const startQueue = useQueueSchedulerStore((s) => s.startQueue)
  const pauseQueue = useQueueSchedulerStore((s) => s.pauseQueue)
  const stopQueue = useQueueSchedulerStore((s) => s.stopQueue)
  const updateConfig = useQueueSchedulerStore((s) => s.updateConfig)

  const handleStart = () => startQueue()
  const handlePause = () => pauseQueue()
  const handleStop = () => stopQueue()
  const handleConfig = (config) => updateConfig(config)

  return (
    <div>
      <button onClick={handleStart}>Start</button>
      <button onClick={handlePause}>Pause</button>
      <button onClick={handleStop}>Stop</button>
      <button onClick={() => handleConfig({ maxConcurrentSessions: 4 })}>
        Set Max 4
      </button>
    </div>
  )
}

---

Interactive Demos

Queue Item Status Demo

:::demo QueueItemStatusDemo #QueueItemStatusDemo.tsx :::

Scheduler Config Demo

:::demo SchedulerConfigDemo #SchedulerConfigDemo.tsx :::

---

Configuration

Scheduler Config

Setting	Type	Default	Description
maxConcurrentSessions	number	2	Maximum sessions running simultaneously
sessionIdleTimeoutMs	number	60000	Idle session timeout in milliseconds
resumeKeySessionBindingTimeoutMs	number	300000	Resume key binding timeout in milliseconds

Queue Item Structure

interface QueueItem {
  item_id: string;
  issue_id?: string;
  sessionKey?: string;
  status: QueueItemStatus;
  execution_order: number;
  created_at?: number;
  updated_at?: number;
}

---

Accessibility

• Keyboard Navigation:

  • Tab - Navigate through queue items and controls
  • Enter/Space - Activate buttons
  • Escape - Close dialogs

• ARIA Attributes:

  • aria-label on control buttons
  • aria-live regions for status updates
  • aria-current for active queue item
  • role="list" on queue items list

• Screen Reader Support:

  • Status changes announced
  • Progress updates spoken
  • Error messages announced

---

Related Links

• Issue Hub - Unified issues, queue, and discovery management
• Terminal Dashboard - Terminal-first workspace with integrated queue panel
• Discovery - Discovery session tracking
• Sessions - Session management and details