misospace/dispatch

Kanban for AI agent work.
Dispatch is a harness-agnostic Kanban and work dispatch layer for AI agents. It turns GitHub Issues and PR follow-ups into claimable queues, tracks agent runs, manages status transitions, and keeps an audit trail while GitHub remains the source of truth.
Tech Stack
- **Next.js**: 16.2.6 (App Router)
- **React**: v19
- **Prisma**: v7
- **Node**: v24 (Dockerfile uses node:24-bookworm-slim)
- **TypeScript**: v6
- **Tailwind CSS**: v4
Architecture
Source of Truth Rules
1. **GitHub is the authoritative source** for all issue/PR data
2. **Dispatch Postgres** stores:
- Cached issue metadata (not the authoritative source)
- Local project metadata
- Agent runs
- Audit logs
3. **Dispatch does NOT**:
- Mount agent harness configuration files
- Require access to an agent harness local workspace
- Use GitHub Projects
- Require cluster-admin or broad Kubernetes RBAC
- Automatically close or complete tasks
Data Flow
Execution Lanes
Issues are classified into execution lanes that control agent queue behavior and claimability. The default setup provides two lanes: default (standard work) and backlog (non-actionable). Lanes are fully configurable via the DISPATCH_LANE_CONFIG_JSON environment variable, supporting custom lane IDs, migration aliases, and role-based classification routing. See Configurable Execution Lanes for details.
Required Labels
Status Labels
- status/backlog - Issue needs triage/grooming; not yet ready for agents
- status/ready - Issue is groomed and actionable; available for agents to claim
- status/in-progress - Issue is being worked on
- status/in-review - Issue has an open PR pending review/merge
- status/blocked - Issue is parked out of agent circulation; excluded from the work queue. A block carrying a blockedReason needs a human; one without a reason is picked back up by the groomer
- status/done - Issue is completed (closed)
Owner Labels
- owner/* - Issue is owned by a specific person (e.g., owner/alice, owner/bob). The Board Owner filter is derived only from synced owner/* labels, not GitHub assignees.
Agent Labels
- agent/* - Issue is assigned to or being worked on by an agent (e.g., agent/alpha, agent/beta). The Board Agent filter is derived only from synced agent/* labels, not AgentRun names, configured agents, or GitHub assignees.
Claim Ownership and Reconciliation
- A claim is not proof of active execution and missing telemetry is not proof of abandonment. The proposed ownership state model, evidence hierarchy, compatibility/migration policy, and bounded reconciliation transitions are specified in Ownership Reconciliation Design.
Project Labels
- Optional: project/* labels may exist on issues, but Dispatch Projects groups issues by repository by default.
Priority Labels
- priority/p0 - Critical
- priority/p1 - High
- priority/p2 - Medium
- priority/p3 - Low
Type Labels
- type/bug
- type/feature
- type/chore
- type/research
- type/security
Environment Variables
Preferred Variables (v0.2.1+)
| Variable | Required | Description |
|----------|----------|-------------|
| DATABASE_URL | Yes | PostgreSQL connection string (canonical) |
| GITHUB_TOKEN | Yes | GitHub Personal Access Token or GitHub App token (fallback when GitHub App auth is not configured) |
| DISPATCH_AGENT_TOKEN | Yes | Bearer token for agent API authentication — the **maintainer-tier** token, with full rights on every route |
| DISPATCH_MAINTAINER_TOKEN | No | Optional alias for the maintainer-tier bearer token; identical rights to DISPATCH_AGENT_TOKEN |
| DISPATCH_WORKER_TOKEN | No | Legacy **unbound** worker-tier bearer token for autonomous executors. Restricted to the route allowlist in src/lib/auth.ts (WORKER_ALLOWLIST); every other route returns 403 naming the required tier. It carries no agent identity, so identity-scoped worker routes require DISPATCH_WORKER_TOKENS instead; a deprecation warning is logged at boot. Must be a distinct value — a token that duplicates a maintainer token resolves to the lower worker tier (fail-closed). See Token Tiers |
| DISPATCH_WORKER_TOKENS | No | Optional **bound** worker credentials, comma- or newline-separated agentName:token pairs (e.g. alpha: ,bravo: ). The caller's identity is derived from the token — never x-agent-name or a body agentName — and a bound worker may only act for its own agent (status additionally scoped to its assigned issues). A token bound to two agents is rejected (fail-closed). See Token Tiers |
| GITHUB_REPOSITORIES | Yes | Bootstrap seed config for repos to track. Accepts comma-separated or newline-separated values (e.g., myorg/repo1,myorg/repo2 or myorg/repo1 on separate lines). Repos can also be managed via Dispatch UI or /api/automation/repos after initial setup. |