# task-queue

> Manage long-running work with a file-based task queue. Use when starting a high-level goal (research, building, investigation), logging progress during work, or marking objectives complete. Also used by heartbeat to detect and resume stalled tasks.

- Author: Nate Hood
- Repository: natehood96/openclaw-config
- Version: 20260206142107
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/natehood96/openclaw-config
- Web: https://mule.run/skillshub/@@natehood96/openclaw-config~task-queue:20260206142107

---

---
name: task-queue
description: Manage long-running work with a file-based task queue. Use when starting a high-level goal (research, building, investigation), logging progress during work, or marking objectives complete. Also used by heartbeat to detect and resume stalled tasks.
---

# Task Queue

Track long-running work so it can be resumed if interrupted.

## When to Use This

**Create a task** when you're starting a high-level goal:
- Research, investigation, analysis
- Building something (app, page, system)
- Multi-step work that could be interrupted

**Don't create a task** for:
- Quick answers
- Single-step edits
- Lookups

## Creating a Task

When starting a high-level goal:

```bash
~/.openclaw/workspace/skills/task-queue/scripts/create-task.sh "Short title" "Full description of the goal"
```

- **Title**: Short, scannable (shows in status reports)
- **Description**: Full context for whoever works on it

Output: `CREATED|task_20260205_143000_abc123`

Save that `task_id` — you'll need it for logging and completion.

## Logging Progress

Log your intent as you work. This is append-only — never edit previous entries.

```bash
~/.openclaw/workspace/skills/task-queue/scripts/append-progress.sh <task_id> "What you're doing"
```

**What to log:**
- What you're about to try
- What happened (worked / failed / partial)
- What you're doing next (or pivoting to)

**Example log entries:**
- "Starting: Looking for competitor pricing pages"
- "Found 3 competitors with public pricing. Extracting data."
- "Competitor A: $29/49/99 tiers. Moving to Competitor B."
- "Hit a paywall on Competitor C. Trying Wayback Machine instead."
- "Got historical pricing from Wayback. Compiling results."

**Log often.** If you stop unexpectedly, the next agent needs to know where you left off.

## Completing a Task

When the **original objective is satisfied**, mark it complete:

```bash
~/.openclaw/workspace/skills/task-queue/scripts/complete-task.sh <task_id>
```

**Before completing, ask yourself:**
- Go back to the original request in `request/<task_id>.md`
- Is that goal achieved?
- If yes → complete it
- If no → keep working

**You must complete tasks.** Incomplete tasks will be flagged by heartbeat as stalled.

## Checking Task Status

See all active tasks (machine-readable):

```bash
~/.openclaw/workspace/skills/task-queue/scripts/check-queue.sh
```

Output format: `STATUS|TASK_ID|TITLE|AGE_MINUTES`

| Status | Meaning | Action |
|--------|---------|--------|
| `NEW` | Created but not started | Start working on it |
| `ACTIVE` | Progress logged <10min ago | Being worked on — leave it |
| `STALE` | Progress logged >10min ago | Needs to be resumed |
| `ORPHAN` | No request file | Auto-deleted |
| `EMPTY` | No tasks in queue | Nothing to do |

## Status Report (Human-Readable)

For a text-message friendly summary:

```bash
~/.openclaw/workspace/skills/task-queue/scripts/status-report.sh
```

Returns a formatted report with emojis, or **nothing if queue is empty**.

Use this during heartbeat to send status updates to the user.

## Resuming a Stale Task

If you're picking up a stale task:

1. Read the original request: `~/.openclaw/workspace/memory/tasks/request/<task_id>.md`
2. Read the progress log: `~/.openclaw/workspace/memory/tasks/progress/<task_id>.md`
3. Log that you're resuming: `append-progress.sh <task_id> "Resuming: <where you're picking up>"`
4. Continue the work
5. Complete when done

## Directory Structure

```
~/.openclaw/workspace/memory/tasks/
├── queue/      # Active task markers
├── request/    # Original goal descriptions
├── progress/   # Append-only work logs
└── completed/  # Finished task markers
```