Task Queue API

profClaw ships with two queue backends: BullMQ (Redis-backed, for pro mode) and an in-memory queue (for pico/mini mode). Both expose the same HTTP API.

Queue Architecture

Task Created
    |
    v
[pending] ---> [queued] ---> [in_progress] ---> [completed]
                                  |
                                  v (on failure)
                             [failed] ---> DLQ (after maxRetries)

BullMQ queue name: ai-tasks (configurable via queue.name in settings.yml)
Notification queue: ai-task-notifications
Redis URL: REDIS_URL env var or settings.yml
Retry: exponential backoff, configurable attempts

GET /api/queue/status

Get current queue depth and worker status.

curl http://localhost:3000/api/queue/status --cookie "profclaw_session=<token>"

Response 200

{
  "mode": "bullmq",
  "queues": {
    "tasks": {
      "pending": 5,
      "queued": 2,
      "inProgress": 1,
      "completed": 142,
      "failed": 3
    }
  },
  "workers": {
    "tasks": { "running": true, "concurrency": 10 },
    "notifications": { "running": true, "concurrency": 5 }
  },
  "deadLetterQueue": {
    "pending": 0,
    "resolved": 12,
    "discarded": 1,
    "total": 13
  }
}

GET /api/dlq

List tasks in the dead letter queue.

curl "http://localhost:3000/api/dlq?limit=20" --cookie "profclaw_session=<token>"

Response

{
  "items": [
    {
      "id": "dlq_01",
      "taskId": "task_05",
      "title": "Failing task",
      "attempts": 3,
      "lastError": "Connection timeout",
      "createdAt": "2026-03-12T08:00:00Z",
      "status": "pending"
    }
  ],
  "total": 1
}

POST /api/dlq/:id/retry

Move a DLQ item back to the active queue for re-processing.

curl -X POST http://localhost:3000/api/dlq/dlq_01/retry

POST /api/dlq/:id/discard

Mark a DLQ item as discarded (won’t be retried automatically).

curl -X POST http://localhost:3000/api/dlq/dlq_01/discard

Queue Configuration

Configure via settings.yml:

queue:
  name: ai-tasks
  notificationName: ai-task-notifications
  concurrency: 10
  notificationConcurrency: 5
  redis:
    url: redis://localhost:6379
  retry:
    attempts: 3
    backoff: 1000
    type: exponential   # or "fixed"

Or via environment variables:

REDIS_URL=redis://localhost:6379
POOL_MAX_CONCURRENT=50
POOL_TIMEOUT_MS=300000

In-Memory Queue

When Redis is not available, profClaw falls back to an in-memory queue (src/queue/memory-queue.ts). The in-memory queue:

Supports the same TaskStatus lifecycle
Does not persist across restarts
Has no cursor-based pagination (offset only)
Suitable for pico and mini deployment modes

Failure Handler

The FailureHandler (src/queue/failure-handler.ts) intercepts task failures and:

Increments the retry counter
Applies exponential backoff delay
Re-queues the task if attempts < maxRetries
Moves the task to the DLQ after maxRetries exhausted
Sends an in-app notification for DLQ entries

Webhook Queue

The webhook queue (src/queue/webhook-queue.ts) handles outbound webhook delivery with automatic retry on failure. Configure delivery endpoints via POST /api/webhooks.

Tasks API - Create and manage tasks in the queue
profclaw queue - Inspect queue status from the CLI
Deployment Modes - When to use BullMQ vs in-memory
Configuration Overview - Queue settings in settings.yml

API Overview

Authentication

Chat

Agents

Tasks

Memory

Integrations

System

Queue Architecture

GET /api/queue/status

GET /api/dlq

POST /api/dlq/:id/retry

POST /api/dlq/:id/discard

Queue Configuration

In-Memory Queue

Failure Handler

Webhook Queue

​Queue Architecture

​GET /api/queue/status

​GET /api/dlq

​POST /api/dlq/:id/retry

​POST /api/dlq/:id/discard

​Queue Configuration

​In-Memory Queue

​Failure Handler

​Webhook Queue

​Related

Queue Architecture

GET /api/queue/status

GET /api/dlq

POST /api/dlq/:id/retry

POST /api/dlq/:id/discard

Queue Configuration

In-Memory Queue

Failure Handler

Webhook Queue

Related