Alpha. Things may break. You've been warned.
External review: REVIEW.md — brutally honest senior/staff engineer audit of the codebase, docs, and spec/impl divergence. The review itself is excellent: specific, evidence-backed, correctly distinguishes real engineering (SQLite concurrency core) from vibe-coded packaging (stale docs, missing CI, false README claims). Worth reading before contributing.
Coordination protocol for AI agents. SQLite-backed. Agent-agnostic.
No server, no daemon, no queues. Just a shared database file agents use to claim, track, review, and finish work. Single Go binary plus SQLite.
curl -sfL https://raw.githubusercontent.com/mrSamDev/taskbind/main/install.sh | shThe curl pipe install works fine for trusted environments. For production, grab the binary from releases and verify the checksum.
What: SQLite-backed coordination protocol for AI agents. Single binary, no server.
Why: Agents kept overwriting each other's updates, forgetting to mark things done, or picking up work already claimed. Markdown files became noise fast. The answer was a database. Every state change is a transaction, so two agents can't claim the same task. If one crashes, its lease expires and another picks it up, same as Rust's ownership model: one owner at a time, released when the owner disappears.
When: Multiple AI agents on the same machine or shared filesystem need durable coordination without Redis or Postgres. Skip it when you need cross-network coordination, real-time push notifications, or thousands of concurrent workers.
The .db file is the only coordination point.
Use: Multiple AI agents on same machine/shared filesystem need durable coordination. Crash recovery. Task ownership. Tested 3-10 concurrent agents, up to 50.
Skip: Cross-network agents. Real-time push notifications. Thousands of concurrent workers. Use Temporal, Celery, or Kafka instead.
curl -sfL https://raw.githubusercontent.com/mrSamDev/taskbind/main/install.sh | sh
taskbind init --harness pi
# Product owner workflow: an LLM reads your spec or roadmap, writes a task
# proposal, you approve, then it dispatches. See the dispatch-plan and
# approve-plan skills under internal/bootstrap/embed/skills/manager/.
# For simple plans, the built-in parser works too.
taskbind init --harness pi --plan plan.md
taskbind --debug task dispatch --title "Set up auth" --role worker --priority 10
taskbind task claim-next --agent my-agent --role worker
taskbind task log-progress TASK-1 --agent my-agent --note "Working"
taskbind task complete TASK-1 --agent my-agentA short table since these are reference docs:
| Command | Who | What |
|---|---|---|
task dispatch --title --role |
anyone | Create a task as TODO |
task claim-next --agent --role [--count N] |
worker | Atomically grab top task(s) |
task claim <id> --agent [--transfer --to] |
worker | Claim by ID or transfer claim |
task log-progress <id> --agent --note |
worker | Log progress, renew lease |
task extend-lease <id> --agent [--minutes] |
worker | Renew lease without state change |
task block <id> --agent --reason |
worker | Mark blocked, drop lease |
task complete <id> --agent [--review] |
worker | Mark done or submit for review |
task view <id> |
anyone | Full details plus notes and history |
task search --status --role --agent |
manager | Filter the board |
task approve <id> --agent |
reviewer | IN_REVIEW to DONE (single) |
task approve --all --agent [--project] |
reviewer | Batch approve all IN_REVIEW |
task reject <id> --agent --reason |
reviewer | IN_REVIEW to TODO |
taskbind plan lint |
manager | Detect dep cycles, unknown deps |
taskbind status [--burndown] [--project] |
anyone | Status counts or progress bars |
batch claim --agent --role [--count N] |
worker | Claim multiple tasks atomically |
batch complete --ids --agent [--to-review] |
worker | Complete multiple tasks |
prune [--before] [--dry-run] |
ops | Clean old events and notes |
init --harness --plan --dir |
setup | Scaffold DB and agent files |
TODO ── claim-next ──> IN_PROGRESS ── complete --review ──> IN_REVIEW ── approve ──> DONE
│ │
│ block │ reject
▼ ▼
BLOCKED TODO
Reviewers don't need to claim IN_REVIEW tasks. They just approve or reject.
Agents don't ship with taskbind knowledge. Skills teach them. Each role gets its own set of skill files — the agent reads its role's skills and learns the protocol.
These are the protocol skills — they teach coordination, not software engineering. They're the moat. Different agents (Claude Code, PI, Codex, Gemini) all read the same skill files. The agents change. The protocol stays.
| Role | Skills | What the agent learns |
|---|---|---|
manager/ |
dispatch-task, dispatch-plan, approve-plan, review-backlog, view-task | Plan work, dispatch tasks, review progress |
worker/ |
claim-next-task, claim-task, log-progress, complete-task, block-task | Claim tasks, report progress, finish work |
reviewer/ |
claim-review, approve-task, reject-task | Review submissions, approve or reject |
taskbind binary = the protocol engine
taskbind skills = the agent runtime (one per role)
Agent runtime = Claude Code, PI, Codex, Gemini, ...
You can add custom task skills alongside protocol skills. These teach an agent how to do the work, not how to coordinate. For example skills/worker/deploy-to-prod.md or skills/manager/sprint-review.md. Protocol skills handle coordination; task skills handle domain logic.
Source: internal/bootstrap/embed/skills/
Manager Workers Reviewers
│ │ │
├── dispatch tasks ────────>│ │
│ ├── claim-next │
│ ├── log-progress │
│ ├── complete --review ─────>│
│ │ ├── approve │
│ │ ├── reject │
│<── search --status BLOCKED│ │
└── unblock or reassign ───>│ │
cmd/taskbind/main.go CLI entrypoint
internal/
bootstrap/ Init, plan parsing, agent and skill templates
bootstrap/taskbind_extension.go Pi extension (TypeScript template)
storage/ SQLite connection, schema, migration
task/ Models, queries, service logic
internal/bootstrap/embed/skills/ Embedded skill templates (canonical source)
manager/ dispatch-task, dispatch-plan, approve-plan, review-backlog, view-task
worker/ claim-next-task, claim-task, log-progress, complete-task, block-task
reviewer/ claim-review, approve-task, reject-task
examples/ Integration guides for pi and Claude Code
Drop an executable in .taskbind/hooks/ named after an event. The hook gets JSON on stdin with the event type and task details. Each hook has a 30-second timeout. Errors are logged to stderr but the operation continues. Missing hooks are silently ignored.
| Event | When |
|---|---|
task.created |
Task dispatched |
task.claimed |
Agent claims |
task.progress |
Progress logged |
task.completed |
Task finished |
task.submitted_for_review |
Submitted |
task.transferred |
Claim transferred to another agent |
task.blocked |
Blocked |
review.approved |
Approved |
review.rejected |
Rejected |
Chain multiple hooks by adding a .d/ directory. The single file runs synchronously. The .d/ hooks run concurrently, so a slow Slack notifier won't block the caller.
.taskbind/hooks/
├── task-created
├── task-completed
└── task-completed.d/
├── slack
├── metrics
└── dashboard
taskbind init # interactive prompt
taskbind init --harness pi # pi extensions
taskbind init --harness claude # Claude Code agents
taskbind init --harness generic # plain .agents/ directory
taskbind init --harness pi --plan plan.mdThe plan parser handles markdown headings with optional [p1] priority hints and JSON arrays.
## Set up auth [p1]
- Implement login endpoint
- Add JWT middleware[
{"title": "Fix auth bug", "role": "worker", "priority": 1}
]For real plans (specs, PRDs, anything with sections and tables and timelines), the Go parser won't cut it. Use the LLM-driven skills instead. An agent reads the plan, understands what it describes, and writes a proposal to .taskbind/tasks-proposal.md. You review it, check the items you want, then the agent dispatches each one. No brittle regex, no parser changes. Just the LLM's ability to read a document and figure out what work it describes.
Agent reads plan.md, writes .taskbind/tasks-proposal.md
You review and check [x] on approved items
Agent reads the proposal and dispatches each checked task
The skills live at internal/bootstrap/embed/skills/manager/dispatch-plan.md and internal/bootstrap/embed/skills/manager/approve-plan.md.
taskbind --debug task claim-next --agent alice --role workerPrints database ops alongside normal output. Useful for debugging lock issues, WAL behavior, and multi-agent timing.
Scale: 3-10 concurrent agents works fine. Past 50 you'll see contention on claim-next. Past 1000, SQLite becomes the bottleneck — switch to Postgres or a distributed queue.
Backup: WAL mode lets you safely copy the .db file while the system runs. Run taskbind prune --before 30d periodically, then VACUUM to reclaim space.
Fixes needed: See REVIEW.md for 5 high-priority refactors. Each has a one-liner solution. Follow YAGNI — build only what breaks first.
One .db file per project, shared by all agents. No server. Two agents calling claim-next at the same time get different tasks because SQLite serializes writes. A claimed task has a 15-minute lease. The log-progress command renews it. If an agent crashes, the lease expires and the next claim-next reclaims the task. The WAL file checkpoints itself every 1000 pages so it doesn't eat your disk.
Worker-A claims TASK-1. Worker-A crashes.
15 minutes later the lease expires.
Worker-B calls claim-next and gets TASK-1.
Every command prints stable JSON to stdout. Empty work returns {}. Errors go to stderr as {"error":"..."} with exit code 2. Skill files (embedded in the binary, written by taskbind init) teach agents the protocol. No tool-calling framework needed.
- examples/pi-subagents.md -- three-coder setup
- examples/claude-code-subagents.md -- Claude Code coordination
go build -o taskbind ./cmd/taskbind/Requires Go 1.24 or later. Pure Go, no CGo.
MIT