pi-queue is a lightweight task runner for the pi coding agent. It accepts tasks through a webhook, shows them in a dashboard for human approval, then lets pi execute each approved task in an isolated git worktree managed by awt.

1. Receive — External tools (Linear, GitHub, Slack, etc.) submit tasks via POST /api/tasks with a bearer token
2. Review — Tasks appear as "pending" in the web dashboard for human review
3. Approve — A human approves (or rejects) each task from the dashboard
4. Execute — A background worker picks up approved tasks, creates an isolated git worktree via awt, and runs pi with the task prompt
5. Deliver — On completion, awt pushes the branch and creates a PR

# Install dependencies
npm install

# Copy and configure environment
cp .env.example .env
# Edit .env
# Minimum required: WEBHOOK_SECRET, API_ACCESS_TOKEN, DASHBOARD_USER, DASHBOARD_PASSWORD

# Run database migrations
npm run db:migrate  # optional; schema is also created on startup when needed

# Start dev server (auto-reloads)
npm run dev

The dashboard is at http://localhost:3000.

cp .env.example .env
# Edit .env with your values
docker compose up --build

See DEPLOYMENT.md for full instructions. I picked Fly.io because it provides a public URL without needing to buy a custom domain.

cp .env.example .env
# Fill in GIT_REPO_URL, WEBHOOK_SECRET, API_ACCESS_TOKEN, DASHBOARD_USER, DASHBOARD_PASSWORD
# Optional: set PUBLIC_ORIGIN for custom domains, or we'll infer the fly.io URL automatically from the app name
./scripts/deploy.sh

POST /api/tasks is protected by Authorization: Bearer <WEBHOOK_SECRET>. All other /api/* endpoints require either:

• Authorization: Bearer <API_ACCESS_TOKEN>
• or dashboard basic auth credentials (DASHBOARD_USER / DASHBOARD_PASSWORD) The server exits at startup if DASHBOARD_USER, DASHBOARD_PASSWORD, or API_ACCESS_TOKEN is missing. State-changing admin routes also enforce same-origin Origin/Referer checks.

Create a new task. Requires Authorization: Bearer <WEBHOOK_SECRET>. Input is validated with bounded sizes (title, prompt, source, externalId, and metadata byte size).

{
  "title": "Fix login validation",
  "prompt": "The login form accepts empty passwords. Fix the validation in src/auth.ts.",
  "priority": 1,
  "source": "linear",
  "externalId": "LIN-456"
}

Returns 201:

{ "id": "abc123", "status": "pending" }

List tasks. Requires API auth (bearer token or dashboard basic auth). Optional query params: status, limit, offset. limit and offset are bounded by server caps.

Get full task details including output. Requires API auth.

Get the raw captured RPC/tool event stream for a task. Requires API auth.

Approve a pending task for execution.

Reject a pending task. Optional body: { "reason": "..." }.

Delete a non-running task.

There are lots of presets for length, etc since the point of the API is to be public facing.