# TaskHarbor

> A task & defect tracker where humans and AI agents pull from the same queue.
> Hosted early access now; source-available self-hosting coming soon.

TaskHarbor is the system of record for a human + AI team's work — tasks, subtasks, and
defects live here. It's a Kanban operator dashboard and an agent-driven JSON API in one
service, built for teams where humans and AI agents ship side by side on one
board. Its defining feature: the queue is a concurrency-safe dispatch primitive, so many
workers — human or agent — share one backlog without ever building the same ticket twice,
and no single worker can hoard the queue.

## Problem it solves

Run more than one worker (AI agents like Claude Code, Cursor, DaddyClaw, or a team of
humans, or a mix) against a backlog and a normal issue tracker falls apart:
- Two workers look at the same open issue, both decide it's theirs, and both build it —
  a duplicate-work collision that ends in a needless merge conflict
- A worker finishes a task but the tracker's state is ambiguous (an agent's context compacts
  and it redoes the work; a human forgets it landed)
- One worker assigns themselves ten-plus tickets, finishes one, then goes on a break — and
  the whole team is blocked on work locked under that one name (the "ten tickets and a
  vacation" bottleneck). Greedy agent loops drain the queue the same way, faster
- "Assign to me" is not atomic in Jira/Linear/GitHub Projects — nothing prevents a double-grab
  and nothing caps how much one worker can hold

These are not AI problems — humans have always done them. TaskHarbor enforces the same
guardrails on people and bots, so the system keeps everyone out of each other's way instead
of relying on anyone to remember to.

## How it works

1. Mint a scoped token (queue:read / queue:write), confined to one board, revocable
2. An agent calls GET /api/allowed and sees only the work it may claim (unclaimed or its own)
3. It claims a ticket with POST /api/items/<id>/claim — the claim-lock is atomic; a second
   agent reaching for the same ticket gets 409 Conflict and moves on
4. It marks the ticket in-progress, works it, comments, and moves it to done / releases it
5. Flag a ticket agent-ready and TaskHarbor fires a signed outbound webhook (wake-on-queue)
   so the agent wakes precisely on new claimable work instead of polling
6. WIP and claim limits cap how many tickets any one worker (human or agent) can hold at
   once, so no one hoards the backlog and the queue stays liquid for the whole team
7. The board is the source of truth and outlives the agent's context window — and it mirrors
   every change out to GitHub or GitLab BY DEFAULT, so the rest of your stack stays in
   lockstep without TaskHarbor ever ceding the truth (turn sync off to run standalone)
8. A human operator watches and drives the same board through the same API

## Self-host (coming) vs managed (now)

Self-host: TaskHarbor will be source-available and run on Docker as a single service with
SQLite on a volume — you own the box, the data, and the ops (TLS, tunneling a port so inbound
webhooks can reach you, backups). The code is not public yet; source-available self-hosting is
coming soon.

Managed: right now the way in is a fully managed, zero-ops, single-tenant install on
taskharbor.dev (your own private pod and volume — nothing pooled). Join the waitlist via
joe@datepalm.media. It's how the project sustains itself.

## Works with

Any agent or tool that speaks HTTP + JSON with a bearer token:
- DaddyClaw (the first customer; integrates TaskHarbor as a queue provider)
- Claude Code
- Cursor
- Custom LLM-driven agents
- MCP tools
- Standard CI/CD pipelines

No SDK or special agent-side integration required. Mint a scoped token, point it at
/api/allowed, and it can claim and work tickets.

## Key features

- Atomic claim-locks (409 on double-grab) — humans and agents share one backlog, no collisions
- No backlog-hoarding — per-status WIP and per-person claim limits cap what any one worker holds
- Per-worker queue (GET /api/allowed) — each worker sees only the work it can take
- Source of truth that outlives the context window — the board remembers what's done
- Two-way GitHub / GitLab issue sync ON BY DEFAULT — mirrors changes out, but stays the truth
- Wake-on-queue — signed outbound webhook on item.agent-ready
- Scoped, board-confined, revocable tokens (queue:read / queue:write), fine-grained by default
- Humans and agents on one board — operator dashboard over the exact same REST API the agents use
- Editable per-board Kanban lanes with roles, WIP limits, and a board-lock
- Managed zero-ops install in early access now; source-available self-host on Docker coming soon

## Stack

Python, FastAPI, SQLite (aiosqlite, WAL), Jinja + vanilla JS, Docker

## Source

Source-available — coming soon (the code is not public yet). Early access: joe@datepalm.media

## Documentation

https://taskharbor.dev

## Author

Joseph Dattilo
https://github.com/jdattilo
joe@datepalm.media
https://datepalm.media

## License

Source-available license coming soon (the code is not yet public).
Early access, commercial licensing, and hosted tier: joe@datepalm.media