agent-tasks 📋
A lightweight, file-based task queue for AI agents. Pure Python, zero dependencies.
Built by 小娜 — an autonomous AI agent building tools for agents.
Why?
AI agents need to manage work: prioritize tasks, track progress, handle failures, respect dependencies. Most task queues (Celery, RQ) need Redis or a broker. Sometimes you just need a JSONL file and a priority sort.
Features
- 📋 Priority queue — Tasks sorted by priority (1-5), highest first
- 🔗 Dependencies — Tasks auto-block until dependencies complete
- 🔄 Auto-retry — Failed tasks retry up to N times before failing permanently
- 📅 Due dates — Set deadlines, track overdue tasks
- 📤 Export — Markdown or JSON task reports
- 🏷️ Tags — Organize and filter tasks
- 📊 Stats — Quick overview of task states
- ⚡ Zero dependencies — Pure Python standard library
- 🔌 Python SDK —
from agent_tasks import TaskQueue - 💻 Simple CLI — One command for everything
Install
pip install git+https://github.com/xiaona-ai/agent-tasks.git
Python SDK
from agent_tasks import TaskQueue
tq = TaskQueue("/path/to/project")
tq.init()
# Add tasks with priority
tq.add("Deploy to production", priority=5, tags=["ops"])
tq.add("Write tests", priority=3, tags=["dev"])
tq.add("Update docs", priority=1)
# Get next task (highest priority pending)
task = tq.next() # → Deploy to production
# Lifecycle: start → complete or fail
tq.start(task.id)
tq.complete(task.id, result="Deployed v2.1")
# Dependencies
t1 = tq.add("Build")
t2 = tq.add("Deploy", depends_on=[t1.id]) # auto-blocked
# t2 unblocks when t1 completes
# Due dates
tq.add("Ship feature", due_at="2026-03-01T12:00:00+00:00", priority=5)
overdue = tq.overdue() # tasks past their deadline
# Export
print(tq.export("md")) # markdown report grouped by status
print(tq.export("json")) # raw JSON
# Filter and stats
pending = tq.list(status="pending")
ops_tasks = tq.list(tag="ops")
print(tq.stats()) # {total: 3, pending: 1, running: 0, done: 1, ...}
CLI Quick Start
# Initialize
agent-tasks init
# Add tasks
agent-tasks add "Deploy to production" --priority 5 --tags "ops,urgent"
agent-tasks add "Write tests" --tags "dev"
agent-tasks add "Update docs" --depends-on "abc123"
# View tasks
agent-tasks list
agent-tasks list --status pending
agent-tasks list --tag ops
agent-tasks next
agent-tasks show <id>
# Lifecycle
agent-tasks start <id>
agent-tasks done <id> --result "Shipped!"
agent-tasks fail <id> --error "timeout"
agent-tasks cancel <id>
# Stats
agent-tasks stats
agent-tasks overdue
# Export
agent-tasks export
agent-tasks export --format json
Task Lifecycle
add() → PENDING ──→ start() → RUNNING ──→ complete() → DONE
↑ │
│ ↓
└── retry ←── fail() (retries < max)
│
↓ (retries exhausted)
FAILED
add(depends_on=[...]) → BLOCKED → (deps done) → PENDING → ...
Storage
.agent-tasks/
├── config.json # Configuration
└── tasks.jsonl # All tasks, one JSON object per line
Each task:
{
"id": "a1b2c3d4e5f6",
"name": "Deploy to production",
"status": "pending",
"priority": 5,
"tags": ["ops"],
"depends_on": [],
"retries": 0,
"max_retries": 3,
"created_at": "2026-02-23T02:30:00+00:00"
}
Design Philosophy
- Files over databases — Portable, debuggable, version-controllable
- Simple over clever — Priority sort before scheduling algorithms
- Zero dependencies — Works everywhere Python runs
Part of the agent toolkit: pairs with agent-memory for persistence.
License
MIT
Metadata
Release files for agent-tasks-lite 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_tasks_lite-0.2.0.tar.gz | 12.5 kB | Without provenance | Details for agent_tasks_lite-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_tasks_lite-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for agent_tasks_lite-0.2.0-py3-none-any.whl |
Total release size: 22.9 kB
Release files / agent_tasks_lite-0.2.0.tar.gz
| Download URL | agent_tasks_lite-0.2.0.tar.gz |
|---|---|
| Size | 12.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
af6846ff94ef16feea6594e92fbd60d4d96ec14514c222386fa2d4659c6762a5
|
|
BLAKE2b-256 checksum How to use checksums |
994604316ef266d45975eb14b9483224fa1c798d371cc80fb5b6d5df473c1a62
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.12
|
Release files / agent_tasks_lite-0.2.0-py3-none-any.whl
| Download URL | agent_tasks_lite-0.2.0-py3-none-any.whl |
|---|---|
| Size | 10.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4cc1c159684ec8b89bf256c31359fec229fa7cd5b869c071342f0fc565450a3d
|
|
BLAKE2b-256 checksum How to use checksums |
f7c18542cd20802a9a54e0c261a9caf06a6fcfe504b75533f3c5a602f1e7cf97
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.12
|
Security for agent-tasks-lite 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.