Agent Task Board

A local SQLite task queue and browser board for AI agents working on one machine. Claim tasks atomically, renew fenced leases, hand work to another agent, and request human approval before a result becomes final. Version 0.1.0, MIT licensed.

Quick start

Python 3.11 or newer is required. From this repository, these three commands install the tool, load fictional examples, and open the board server:

python3 -m pip install -e .
atb import examples/tasks.json --json
atb serve --host 127.0.0.1 --port 8765

Visit http://127.0.0.1:8765. The responsive board works offline without a build step, CDN, account, or API key. Use atb serve --read-only for display-only mode. For an isolated environment and headless-agent setup, see AGENTS.md.

{"ok":true,"data":{"imported":3,"skipped":0},"warnings":[]}

Related MCP server: Signal MCP

What is included

• ULID task IDs, priorities (larger values run first), queues, optional assignees, deadlines, tags, JSON inputs/results, and artifact paths.

• SQLite WAL plus BEGIN IMMEDIATE for every state transition; unique active deduplication keys; dependencies with cycle detection.

• Atomic claims, renewable 15-minute leases, and fresh random tokens for every claim. Expired workers cannot complete, fail, or renew a replacement lease.

• Bounded attempts and exponential retry delays: 30, 60, 120 seconds by default, capped at one day. Expired leases return immediately to the queue unless the attempt limit is exhausted. Each claim consumes one attempt.

• Five-field cron schedules, bounded catch-up, comments, reassignment, and an append-only event timeline.

• Human review: needs_approval tasks enter review; only approval unblocks their dependents. Rejection starts a new attempt budget and preserves the prior result for inspection.

• English browser kanban with agent filtering, deadline highlighting, timeline, approval/return controls, notes, and reassignment; read-only mode rejects writes on the server.

• Official Python MCP SDK via stdio, sharing the same business logic as the CLI.

• JSON/CSV import/export, live SQLite backup ZIPs, and optional completion hooks.

CLI reference

Every command accepts --data-dir, --config, --json, and --quiet, before or after the subcommand. All normal command results are one JSON envelope on stdout, including without --json. Errors are structured and return a nonzero exit code. --version also returns JSON. serve and mcp are long-running services.

Additional add options: --body, --assignee, --due, repeatable --tag, repeatable --depends-on, --max-attempts, and --actor. Use atb COMMAND --help for exact parameter names. Lease tokens are returned by claim/heartbeat and must be retained by the claiming worker; list/show/export/Web do not expose them.

Configuration and data

Default data: ./data/tasks.db. Precedence for the directory is CLI --data-dir, ATB_DATA_DIR, TOML data_dir, then ./data. See examples/config.toml. Naive ISO dates and cron expressions use Asia/Shanghai by default. Storage uses UTC with explicit offsets. The browser displays the configured time zone.

Task JSON accepts title, body, queue, assignee, priority, due_at, tags, dedupe_key, blocked_by, params, max_attempts, and needs_approval. JSON export additionally contains task state, events, and schedules. CSV is a task table with nested arrays/objects encoded as JSON cells, UTF-8 with BOM by default; use export --format csv --utf8 for plain UTF-8. CSV does not carry event history or schedules. Imports are transactional, preserve IDs, and skip existing IDs or active dedupe keys. Imported claimed/running tasks require a fresh claim; imported tasks with an existing ID are never updated. JSON imports retain historical task events, assigning fresh local event sequence IDs.

backup uses SQLite's online backup API, including committed WAL changes, and stores tasks.db plus metadata in a timestamped ZIP. To restore, stop all workers and servers, make a backup, then extract into a new empty data directory and start with --data-dir NEW_DIRECTORY. Runtime data and backups are git-ignored.

Run atb tick every minute with cron to generate scheduled tasks and reclaim expired leases even while no workers are polling. Claims also reclaim expired leases. Repeated ticks do not regenerate the same occurrence. Catch-up is capped per schedule per call, and catchup_pending signals more work. Pause/resume skips the paused interval. Schedule occurrence keys override template dedupe_key.

MCP configuration

{
  "mcpServers": {
    "agent-task-board": {
      "command": "/workspace/apps/agent-task-board/.venv/bin/atb",
      "args": ["--data-dir", "/workspace/data/agent-task-board", "mcp"]
    }
  }
}

Tools: create_task, claim_task, heartbeat, complete_task, fail_task, list_tasks, add_comment, get_task, and cancel_task (confirm=true required). Approval is deliberately available through the human CLI/Web workflow rather than the agent tool set. Full generated schemas are in docs/mcp-tools.json. The runtime is pinned to the official SDK's compatible mcp>=1.20,<2 series.

Integrations and optional hooks

Daily digest tools can consume atb list --json and atb events --json, or the JSON export. Reading data does not reclaim leases or generate scheduled work.

Completion hooks are disabled by default. Explicitly set [hooks] enabled=true and a trusted command argv array in TOML to run a local program after the task is committed done; it receives the task JSON on stdin, has a 10-second timeout, and does not run through a shell. No command is taken from task content. A fixed webhook URL additionally requires allow_network=true and has a 5-second timeout. See examples/config.toml. Review tasks trigger hooks only after approval. Delivery success/failure appears in events. Hooks are best effort, not a durable outbox: a process crash after commit can prevent delivery. Hook failure never rolls back a completed task.

Verification

python -m pip install -e '.[dev]'
ruff check .
ruff format --check .
pytest -q --cov=agent_task_board

Tests include ten real processes claiming and completing 1,000 tasks with no duplicate claim, no omission, and one attempt each; token fencing after expiry; renewal; exponential backoff; dependency cycles; review; schedules; import/backup; every MCP tool via the SDK; and HTTP read-only and mutation protections. CI runs Python 3.11 and 3.12 on Ubuntu.

FAQ and boundaries

Does this promise exactly-once external effects? No. Lease fencing protects queue state. A worker that loses its lease must stop; effects performed before a crash may repeat on retry. Make external operations idempotent using task ID.

Can it run across machines? No. Use a local filesystem on one machine. SQLite WAL on network filesystems and distributed workers are outside scope.

Is the web server authenticated? No account system is included. It defaults to loopback and protects mutations against cross-origin browser requests. All local users able to access the service can operate it. Keep it on loopback, or use an authenticated reverse proxy you manage. Read-only mode is a server-side restriction.

Why is a task blocked? Every dependency must be done. Failed, cancelled, or review dependencies keep descendants blocked. Inspect show and events, then resolve or retry the parent. Deleting task history is intentionally unsupported.

Why do queries still show an expired claim? Queries do not change state. Run tick, or let the next claim reclaim it. The worker still cannot mutate an expired lease before reclamation.

How large is the browser view? It displays at most 10,000 tasks; the CLI supports up to 100,000 per list call. Event queries support --after cursor pagination. The board refreshes every ten seconds and task timelines load the first 1,000 events. Use the CLI cursor for longer histories.

Roadmap

Durable hook outbox, paginated browser histories, and optional task archival. No cloud dependency, broker execution, account login, or multi-machine coordination is included. All examples are fictional. See CHANGELOG.md and LICENSE.