Agent Task Queue

Persistent, cross-session task queue for AI agents aligned with the Claude Code Tasks schema. Tasks survive beyond sessions, carry full context including conversation transcripts, and support dependency tracking with blocks/blockedBy. Backed by a git repo with move-based locking for conflict-free multi-agent access.

Prerequisites

Clone the task queue repository:

bash

git clone git@github.com:OlechowskiMichal/agent-task-queue.git ~/.agent-task-queue

All commands below assume the repo is at

~/.agent-task-queue

Quick Reference

Operation	Command	Description
Add	`python3 ~/.agent-task-queue/scripts/add_task.py`	Create a new task
List	`python3 ~/.agent-task-queue/scripts/list_tasks.py`	List/filter tasks
Claim	`python3 ~/.agent-task-queue/scripts/claim_task.py`	Claim a pending task
Complete	`python3 ~/.agent-task-queue/scripts/complete_task.py`	Mark task done
Release	`python3 ~/.agent-task-queue/scripts/release_task.py`	Unclaim a task
Reassign	`python3 ~/.agent-task-queue/scripts/reassign_task.py`	Reassign to different agent
Index	`python3 ~/.agent-task-queue/scripts/render_index.py`	Regenerate root index
Prune	`python3 ~/.agent-task-queue/scripts/prune_completed.py`	Archive old tasks

Adding a Task

Save a task for a future agent session:

bash

python3 ~/.agent-task-queue/scripts/add_task.py \
  --assignee go-expert \
  --subject "Fix error handling in API middleware" \
  --description "The error handler swallows context. Wrap errors with fmt.Errorf." \
  --priority high \
  --project my-api \
  --tags "error-handling,api" \
  --active-form "Fixing error handling" \
  --ttl-hours 48 \
  --blocked-by "3,7" \
  --context-repo "git@github.com:OlechowskiMichal/my-api.git" \
  --context-files "pkg/middleware/error.go,pkg/middleware/error_test.go" \
  --context-notes "See issue #42 for the original bug report"

The script reads

.highwatermark

to assign the next monotonic integer ID, writes the task JSON to

pending/{id}.json

, regenerates the root index, and pushes to the repo.

Listing Tasks

bash

# All pending tasks for an agent
python3 ~/.agent-task-queue/scripts/list_tasks.py --agent go-expert --status pending

# Stale tasks (claimed but exceeded TTL)
python3 ~/.agent-task-queue/scripts/list_tasks.py --stale

# Blocked tasks (unmet dependencies)
python3 ~/.agent-task-queue/scripts/list_tasks.py --blocked

# Tasks for a specific project
python3 ~/.agent-task-queue/scripts/list_tasks.py --project my-api

# Tasks created after a date
python3 ~/.agent-task-queue/scripts/list_tasks.py --since 2026-03-01

Claiming a Task

Start working on a pending task:

bash

python3 ~/.agent-task-queue/scripts/claim_task.py 1 --session-id $(uuidgen)

The script:

Verifies all
```
blockedBy
```
dependencies are completed
Moves the task from
```
pending/
```
to
```
active/
```
Sets
```
owner
```
and
```
metadata.claimed_at
```
Updates
```
status
```
to
```
in_progress
```
Pushes with conflict detection — if another agent claimed it first, the push fails

Completing a Task

bash

python3 ~/.agent-task-queue/scripts/complete_task.py 1 \
  --session-id "$SESSION_ID" \
  --jsonl-path "~/.claude/projects/.../conversation.jsonl" \
  --notes "Fixed by wrapping errors with context in middleware chain"

The task moves to

completed/YYYY-MM/{id}.json

with the conversation transcript reference appended.

Releasing a Task

If you cannot finish a claimed task:

bash

python3 ~/.agent-task-queue/scripts/release_task.py 1

Moves back to

pending/

with

metadata.previously_claimed=true

and

status

reset to

pending

so the next agent knows it was attempted.

Reassigning a Task

Transfer a task to a different agent type:

bash

python3 ~/.agent-task-queue/scripts/reassign_task.py 1 --to re-expert

This is a metadata-only update — it sets

metadata.assignee

to the new agent. No file move occurs. The task stays in its current directory (

pending/

active/

Dependency Management

Tasks support bidirectional dependency tracking via

blocks

and

blockedBy

fields, aligned with the Claude Code Tasks schema.

blockedBy: Array of task IDs that must be completed before this task can be claimed.
```
claim_task.py
```
enforces this — it refuses to claim a task with unresolved blockedBy entries.
blocks: Array of task IDs that are waiting on this task. When a task is completed, the system can check whether downstream tasks are now unblocked.

Both sides are kept in sync: adding task 5 to the

blockedBy

of task 8 also adds task 8 to the

blocks

of task 5.

Cycle detection runs at add time and at claim time. If adding a dependency would create a circular chain (e.g., A blocks B blocks A), the operation is rejected with an error.

bash

# Add a task that depends on tasks 3 and 7
python3 ~/.agent-task-queue/scripts/add_task.py \
  --subject "Deploy after migrations" \
  --blocked-by "3,7"

# List all currently blocked tasks
python3 ~/.agent-task-queue/scripts/list_tasks.py --blocked

Race Condition Handling

All scripts use push-reject, pull-rebase, retry (once). If a claim push is rejected after rebase, it means another agent already claimed the task. The script exits with an error message.

Conversation Linking

Link Claude Code conversation transcripts to tasks when completing:

Pass
```
--jsonl-path
```
with the path to the
```
.jsonl
```
transcript file
The path is stored in the task's
```
metadata.conversations
```
array
Multiple sessions can contribute to the same task

Staleness Detection

Tasks have a

metadata.ttl_hours

field (default: 24). A claimed task is stale when

metadata.claimed_at + ttl_hours < now

. Find stale tasks with

--stale

flag. Release stale tasks manually with

release_task.py

Pruning Completed Tasks

Remove old completed tasks:

bash

# Dry run — show what would be deleted
python3 ~/.agent-task-queue/scripts/prune_completed.py --older-than 90d

# Actually delete
python3 ~/.agent-task-queue/scripts/prune_completed.py --older-than 90d --execute

Task Schema

See references/task-schema.md for the full JSON schema with field descriptions.

Directory Layout

agent-task-queue/
├── .highwatermark              # Monotonic ID counter (single integer)
├── pending/                    # Flat — no agent subdirs
│   └── {id}.json
├── active/
│   └── {id}.json
├── completed/
│   └── YYYY-MM/
│       └── {id}.json
├── index.md                    # Single root index
├── scripts/
│   ├── _lib.py
│   ├── add_task.py
│   ├── claim_task.py
│   ├── complete_task.py
│   ├── list_tasks.py
│   ├── release_task.py
│   ├── reassign_task.py
│   ├── render_index.py
│   └── prune_completed.py
├── AGENTS.md
├── CLAUDE.md
├── TODO.md
└── README.md

dev-task-queue

NPX Install

Tags

SKILL.md Content

Agent Task Queue

Prerequisites

Quick Reference

Adding a Task

Listing Tasks

Claiming a Task

Completing a Task

Releasing a Task

Reassigning a Task

Dependency Management

Race Condition Handling

Conversation Linking

Staleness Detection

Pruning Completed Tasks

Task Schema

Directory Layout