Task Queue

Manage concurrent sub-agent tasks with real-time visibility. Main session stays responsive; heavy work runs in parallel sub-agents tracked by a queue.

Setup

Initialize the queue state file on first use:

cat > /tmp/task-queue.json << 'EOF'
{
  "maxConcurrent": 8,
  "maxSameType": 3,
  "active": [],
  "queued": [],
  "completed": [],
  "stats": { "totalSpawned": 0, "totalCompleted": 0, "totalFailed": 0 },
  "updatedAt": null
}
EOF

Adjust maxConcurrent by machine:

• Low-end (Mac Mini 16GB): 3-4
• Mid-range (Mac Studio 64GB): 6
• Server (64+ cores, 128GB+): 8

Commands

Queue Protocol

On new task (that needs sub-agent)

1. Generate sequential ID: Q-001, Q-002, ...
2. Classify type: research | dev | report | search | translate | analysis | other
3. Check capacity:
   • active.length < maxConcurrent AND same-type count < maxSameType → spawn, add to active
   • Otherwise → add to queued, notify user of position
4. Update /tmp/task-queue.json

On task completion

1. Move from active to completed (keep last 20)
2. Pop next from queued if any, spawn it
3. Update stats
4. Report result to user

On task failure

1. Record in completed with "result": "failed" and reason
2. Notify user with suggestion (retry / alternative / manual)
3. Continue dequeuing — failures don't block the queue

/queue response format

📋 任务队列 (活跃 X/8 | 排队 Y)

🔄 运行中：
  Q-001 [research] 海外媒体分析 (3m ago)
  Q-002 [dev] 修复登录bug (1m ago)

⏳ 排队中：
  Q-003 [report] 周报生成

✅ 最近完成：
  Q-000 [search] KOL筛选 → 成功 (5m)

If empty: report "全空，随时可以塞活"

Data Schema

See references/schema.md for the complete JSON structure of /tmp/task-queue.json.

Dispatch Rules

Decide whether to queue (spawn sub-agent) or handle directly in main session:

Queue it (any one triggers):

• Estimated time > 2 minutes
• Batch operations (bulk search, multi-doc processing)
• Development / code tasks
• Deep research or analysis
• Long document generation
• User sends multiple independent tasks at once

Handle directly (all true):

• Simple Q&A, chat, confirmations
• Quick lookups (read file, check status)
• 1-2 step operations
• Needs multi-turn clarification first

When uncertain, prefer queuing — better to over-spawn than block the main session.

Portable Deployment

To deploy on another machine (e.g., Mac with a different OpenClaw agent):

1. Install this skill to the target agent's skills directory
2. Create /tmp/task-queue.json with the init template above
3. Adjust maxConcurrent for the machine's resources
4. Add /queue trigger to the agent's routing config (AGENTS.md or equivalent)