task-runner

# Task Runner Skill

A persistent, daemon-style task queue. Users add tasks at any time. A dispatcher runs on every
heartbeat to check the queue and execute pending work via subagents. Tasks accumulate, complete,
and are archived — the queue itself never closes.

---

## Two Operating Modes

This skill has **two distinct modes** with different triggers and behaviors:

| Mode | Trigger | Purpose |
|------|---------|---------|
| **INTAKE** | User message containing task intent | Parse message → add tasks to queue → confirm → **immediately run DISPATCHER** |
| **DISPATCHER** | After INTAKE (primary) · Heartbeat/cron (backup) | Read queue → dispatch pending tasks → report completions |

Both modes read and write the **same persistent queue file**.

---

## A1 — Triggers

### Mode 1: INTAKE (user message)

Activate INTAKE mode when the user's message matches any of the following patterns:

| Pattern | Examples |
|---------|---------|
| Explicit task add | "add task", "add these tasks", "task:", "new task" |
| Delegation | "do this for me", "do these for me", "handle these", "can you do X" |
| Framing | "I need you to", "help me with", "I need", "I want you to" |
| List framing | "task list", "my tasks", "queue these", "work on these" |
| Control commands | "skip T-03", "retry T-02", "mark T-01 done", "cancel T-04" |
| Status check | "show tasks", "task status", "what's in the queue", "what are my pending tasks" |
| Compound ask | Any message with 2+ distinct action items (bullets, numbers, "and also", "then") |

**Do NOT activate INTAKE for:**
- Pure single-question lookups answered in one sentence ("what time is it?")
- Scheduling-only requests with no actual task ("remind me in 20 min")
- Single web search requests ("google X")
- The heartbeat systemEvent (that's DISPATCHER mode)

### Mode 2: DISPATCHER (inline after INTAKE, heartbeat, or cron)

Activate DISPATCHER mode when triggered by:
- **Immediately after INTAKE** — runs in the same turn, right after tasks are que...

# task-runner

**Version:** 2.0.0 | **Tier:** general | **Owner:** main agent

A persistent, daemon-style task queue for OpenClaw agents. Tell the agent what you need done — once, or across multiple days — and it will queue your tasks, execute them in the background via subagents, and notify you as each one completes. The queue never closes. You can keep adding tasks forever.

---

## The Core Idea

**Old design:** User sends tasks → agent runs them → done. ❌

**New design:** User sends tasks → tasks go into a queue → dispatcher wakes up periodically → tasks execute in background → user gets notified. ✅

The agent is always ready for your next task, even if the last one hasn't finished yet.

---

## Two Operating Modes

### Mode 1: INTAKE
Triggered when you send a message with tasks. The agent:
1. Parses your message into structured task objects
2. Assigns IDs (T-01, T-02, ...)
3. Appends them to the persistent queue file
4. Confirms: "Added T-07: [description]. Queue now has 3 pending tasks."
5. Done. The dispatcher will execute them.

### Mode 2: DISPATCHER
Triggered every heartbeat (~every 15–20 min) and by a cron job (every 15 min). The agent:
1. Reads the queue
2. If nothing pending/running → silent (HEARTBEAT_OK)
3. If pending tasks → spawns subagents to execute them (up to 2 at a time)
4. Checks running tasks for completion → notifies you when done or blocked

---

## Example: Tasks Added Over Multiple Days

### Monday morning
You send:
```
I need you to:
1. Research the top 5 open-source LLM frameworks and summarize pros/cons
2. Create a markdown comparison table at ~/reports/llm-frameworks.md
```

Agent responds:
```
📋 Added 2 tasks to queue:
• T-01: Research top 5 open-source LLM frameworks
• T-02: Create LLM framework comparison table at ~/reports/llm-frameworks.md

Queue now has 2 pending tasks. Dispatcher will pick these up shortly.
```

Later that day (after dispatcher runs):
```
✅ T-01 done — Researched 5 LLM frameworks: Ollama, LM Studio, llama.c...