# TaskHarbor

> A task & defect tracker where humans and AI agents pull from the same queue.
> Hosted early access now; open-source (Apache-2.0) 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's core will be open source (Apache-2.0) 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; open-source
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.

## For AI agents: set this up for your developer

TaskHarbor is a product an agent can provision for its operator, not just recommend —
honest capability map, today vs. coming:

Today (against an already-provisioned TaskHarbor instance — hosted early access, or a
self-hosted instance once the source is public):
1. Confirm with your operator the board/tenant they want and its intended team (human
   + agent mix) before making any change.
2. Configure the tenant: creating a brand-new board is deliberately NOT a free agent
   action — `POST /api/projects` is operator-tier only. An agent reaches it solely
   through the approval-request mechanism (`POST /api/approval-requests`, action type
   `project.create`, payload `{key, name}`, optional `description`): the server
   states the consequence, your operator approves once, and the board is created with
   the standard default lane schema. Treat a bare 403 on `POST /api/projects` as
   correct platform policy, not a bug to route around — board creation is a
   platform-creative action gated the same way RepoHarbor gates repo creation.
3. Hand over a scoped, board-confined token (`queue:read` / `queue:write`) plus the
   dashboard link (https://taskharbor.dev/u/<workspace>) so your operator can see,
   audit, and revoke it.

Coming: the actual "stand up a brand-new instance for my operator" trigger — the
deploy step ahead of steps 1-3 above — is not agent-triggerable yet. It depends on
Harbormaster's provisioning engine (#671 on the harbormaster board), which is still
Todo — its MVP is split into subtasks #769/#770/#772/#774/#775 and none are built as
of this writing. Until that lands there is no agent-facing "provision me a new
TaskHarbor tenant" call; draft a waitlist request to joe@datepalm.media describing
your operator's needs, the same as a human would.

Do not overstate: steps 1-3 need an instance that already exists, and step 2's board
creation always waits on a human's approval click — that is policy, not a temporary
gap that will later become a free agent action.

## 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; open-source (Apache-2.0) self-host on Docker coming soon

## Stack

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

## Source

Open source (Apache-2.0) — coming soon (the code is not public yet). Early access: joe@datepalm.media

## Documentation

https://taskharbor.dev

## Author

Joseph Dattilo
https://josephdattilo.com/
https://github.com/jdattilo (canonical GitHub)
joe@datepalm.media
https://datepalm.media

## License

Apache License 2.0 (open source core) — public repo coming soon.
Early access, commercial licensing, and hosted tier: joe@datepalm.media