dev-task-queue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Task Queue

Agent任务队列

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.

符合Claude Code Tasks schema的AI Agent跨会话持久化任务队列。任务可跨会话留存，包含对话记录在内的完整上下文，并支持通过blocks/blockedBy进行依赖追踪。基于Git仓库实现，采用基于移动的锁机制，确保多Agent无冲突访问。

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

克隆任务队列仓库：

bash

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

以下所有命令均假设仓库路径为

~/.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

操作	命令	说明
添加	`python3 ~/.agent-task-queue/scripts/add_task.py`	创建新任务
列出	`python3 ~/.agent-task-queue/scripts/list_tasks.py`	列出/筛选任务
认领	`python3 ~/.agent-task-queue/scripts/claim_task.py`	认领待处理任务
完成	`python3 ~/.agent-task-queue/scripts/complete_task.py`	标记任务完成
释放	`python3 ~/.agent-task-queue/scripts/release_task.py`	取消任务认领
重新分配	`python3 ~/.agent-task-queue/scripts/reassign_task.py`	重新分配给其他Agent
生成索引	`python3 ~/.agent-task-queue/scripts/render_index.py`	重新生成根索引
清理	`python3 ~/.agent-task-queue/scripts/prune_completed.py`	归档旧任务

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.

为未来的Agent会话保存任务：

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"

该脚本读取

.highwatermark

文件来分配下一个递增整数ID，将任务JSON写入

pending/{id}.json

，重新生成根索引并推送到仓库。

Listing Tasks

列出任务

bash

undefined

bash

undefined

All pending tasks for an agent

某Agent的所有待处理任务

python3 ~/.agent-task-queue/scripts/list_tasks.py --agent go-expert --status pending

Stale tasks (claimed but exceeded TTL)

过期任务（已认领但超出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

undefined

python3 ~/.agent-task-queue/scripts/list_tasks.py --since 2026-03-01

undefined

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

开始处理待处理任务：

bash

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

该脚本执行以下操作：

验证所有
```
blockedBy
```
依赖项均已完成
将任务从
```
pending/
```
移动到
```
active/
```
设置
```
owner
```
和
```
metadata.claimed_at
```
字段
将
```
status
```
更新为
```
in_progress
```
推送并检测冲突 —— 如果其他Agent已先认领该任务，推送会失败

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.

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"

任务会被移动到

completed/YYYY-MM/{id}.json

，并附加对话记录引用。

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.

如果无法完成已认领的任务：

bash

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

任务会被移回

pending/

，同时设置

metadata.previously_claimed=true

，

status

重置为

pending

，以便后续Agent知晓该任务曾被尝试处理。

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/

将任务转移给其他类型的Agent：

bash

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

这只是元数据更新 —— 将

metadata.assignee

设置为新的Agent，不会移动文件。任务会保留在当前目录（

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

undefined

任务支持通过

blocks

和

blockedBy

字段实现双向依赖追踪，与Claude Code Tasks schema保持一致。

blockedBy：必须先完成的任务ID数组，只有这些任务完成后才能认领当前任务。
```
claim_task.py
```
会强制执行此规则 —— 拒绝认领存在未解决blockedBy项的任务。
blocks：等待当前任务完成的任务ID数组。当任务完成后，系统可检查下游任务是否已解除阻塞。

两者会保持同步：将任务5添加到任务8的

blockedBy

中，同时会将任务8添加到任务5的

blocks

中。

循环检测会在添加任务和认领任务时运行。如果添加依赖会形成循环链（例如A阻塞B，B阻塞A），操作会被拒绝并返回错误。

bash

undefined

Add a task that depends on tasks 3 and 7

添加一个依赖任务3和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

undefined

python3 ~/.agent-task-queue/scripts/list_tasks.py --blocked

undefined

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.

所有脚本均采用“推送-拒绝、拉取-变基、重试（一次）”的机制。如果认领推送在变基后被拒绝，说明其他Agent已先认领该任务，脚本会输出错误信息并退出。

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

完成任务时可将Claude Code对话记录与任务关联：

通过
```
--jsonl-path
```
参数传入
```
.jsonl
```
对话记录文件路径
路径会被存储在任务的
```
metadata.conversations
```
数组中
多个会话可贡献到同一个任务

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

任务包含

metadata.ttl_hours

字段（默认值：24）。当

metadata.claimed_at + ttl_hours < 当前时间

时，已认领的任务会被标记为过期。可通过

--stale

参数查找过期任务，使用

release_task.py

手动释放过期任务。

Pruning Completed Tasks

清理已完成任务

Remove old completed tasks:

bash

undefined

移除旧的已完成任务：

bash

undefined

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

undefined

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

undefined

Task Schema

任务Schema

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

完整的JSON Schema及字段说明请查看references/task-schema.md。

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

agent-task-queue/
├── .highwatermark              # 递增ID计数器（单个整数）
├── pending/                    # 待处理任务目录（无Agent子目录）
│   └── {id}.json
├── active/
│   └── {id}.json
├── completed/
│   └── YYYY-MM/
│       └── {id}.json
├── index.md                    # 根索引文件
├── 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