# Wood Fired Tasks

> Multi-agent coordination for AI coding fleets — MCP server, REST API, and CLI over a shared SQLite backbone with atomic task claiming and real-time SSE events.

- **Type:** MCP server
- **Install:** `agentstack add mcp-wood-fired-games-wood-fired-tasks`
- **Verified:** Pending review
- **Seller:** [Wood-Fired-Games](https://agentstack.voostack.com/s/wood-fired-games)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Wood-Fired-Games](https://github.com/Wood-Fired-Games)
- **Source:** https://github.com/Wood-Fired-Games/wood-fired-tasks
- **Website:** https://www.npmjs.com/package/wood-fired-tasks

## Install

```sh
agentstack add mcp-wood-fired-games-wood-fired-tasks
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Wood Fired Tasks

[](https://github.com/Wood-Fired-Games/wood-fired-tasks/actions/workflows/ci.yml)
[](https://github.com/Wood-Fired-Games/wood-fired-tasks/actions/workflows/install-scripts.yml)
[](LICENSE)

Wood Fired Tasks is open-source coordination infrastructure for fleets of AI coding agents — the missing primitive between "I have one Claude Code session running" and "I have ten of them working the same backlog without stepping on each other." You point Claude Code (or Cursor, Gemini, Codex) and a `tasks` CLI at one shared, SQLite-backed service — over MCP, REST, or the CLI, all at full feature parity — and every surface reads and writes the same source of truth. The coordination primitives are first-class: atomic task claiming with optimistic locking (20 agents race, exactly one wins), workflow automation that auto-unblocks dependents and auto-completes parents as subtasks finish, and a real-time SSE event stream keeping every agent and dashboard in sync. On top of that, a set of `/tasks:*` skills turn a project-level goal into a decomposed, executable, auditable plan — and an optional economic prioritizer (WSJF) can rank the backlog by value-per-effort so the loops drain the most-unblocking work first. Self-hostable and MIT-licensed; one server can be shared by a whole team across Windows, Linux, and macOS.

**What you actually do with it:**

- **Coordinate a fleet on one backlog** — many agents claim, complete, and unblock work against a single shared service without colliding.
- **Go from idea → plan → decompose → execute → audit** with the `/tasks:*` skills (see [The workflow](#the-workflow) and the real-usage [playbook](docs/USAGE_PATTERNS.md)).
- **Run it on-prem for your team** — one self-hosted server, with Windows/Linux/macOS clients all pointed at it ([multi-OS fleet setup](docs/SETUP.md#multi-os-client-fleet-one-shared-on-prem-server)).

**Key capabilities:**

- `/tasks:*` skill files implementing the plan→decompose→loop→audit lifecycle (ship as Claude Code slash commands; the recipes are vendor-neutral)
- MCP server with 31 tools for native agent integration (local SQLite or remote HTTP modes) + a single cross-platform npm install (Linux/macOS/Windows)
- REST API with 59 route handlers across `src/api/routes/` (1 public `/health`; the rest authenticated; a single instance serves up to 52 — OIDC-disabled stubs are mutually exclusive with the live OIDC routes) and a `tasks` CLI with 45 commands
- Atomic task claiming with optimistic locking + workflow automation (parent auto-complete, dependency auto-unblock) for multi-agent coordination
- Real-time Server-Sent Events (SSE) for task/project change notifications
- SQLite database with WAL mode, FTS5 full-text search, and automatic migrations
- **Optional WSJF prioritization** — economic backlog ordering most trackers don't offer: variance-enforced column anchoring (recovers a real ranking from an "everything is high" backlog) and propagation-adjusted effective WSJF (surfaces the prerequisite that unblocks the most downstream value). Opt-in and backward-compatible. [Details ↓](#wsjf-prioritization)

## The workflow

The `/tasks:*` skills turn a high-level goal into a drained, audited backlog. The
canonical lifecycle:

```
 plan ─────▶ /tasks:decompose ─────▶ /tasks:loop      (FLAT — sequential)
(brainstorm   into a dedicated         or
 or your own  project (8–25 tasks    /tasks:loop-dag  (DAG — parallel waves) ─────▶ /tasks:audit
 plan file)   or a dependency DAG)
```

- **`/tasks:decompose `** turns a project goal (or a written plan) into
  8–25 independent leaf tasks or a dependency DAG. It *plans only* — it never executes
  what it creates, refuses blast-radius goals, and supports `--dry-run`.
- **`/tasks:loop` / `/tasks:loop-dag`** drain the backlog autonomously: a subagent
  implements each task, the orchestrator re-verifies with your build/test commands,
  closes it, commits, and moves on. `loop` runs a FLAT backlog in sequence; `loop-dag`
  runs a dependency DAG wave-by-wave in parallel.
- **`/tasks:audit`** grades the closed work against its acceptance criteria.

That is the skeleton. The patterns people actually run — draining a big project across
many context clears, the *surface-and-file* capture loop, scoped subset loops,
branch → PR → independent-review → merge, and the single-threaded **live-verified**
fallback when an autonomous run can't be trusted — are written up with illustrative
command sequences in **[docs/USAGE_PATTERNS.md](docs/USAGE_PATTERNS.md)**.

Because the loops close tasks on agent-written evidence, they ship with
anti-fabrication guardrails (the opt-in `WFT_STRICT_EVIDENCE` server gate, an optional
client-side SHA hook, and skill-level discipline) — see
[docs/RELIABILITY.md](docs/RELIABILITY.md).

## For agents

Coding agents (Claude Code, Cursor, Gemini, Codex, and others) should start with:

1. [AGENTS.md](AGENTS.md) — first-read navigation hub.
2. [docs/AGENT_CONTEXT.md](docs/AGENT_CONTEXT.md) — the vendor-neutral context contract.
3. [.agent-context.json](.agent-context.json) — machine-readable manifest of canonical files and their budgets.

A root [`llms.txt`](llms.txt) (the emerging agent-discovery convention) also
points here, and both it and the curated agent docs ship inside the npm tarball.
Vendor-specific files (`CLAUDE.md`, `.cursor/`, `.gemini/`, `.codex/`) are
adapters and MUST NOT carry unique facts — see `docs/AGENT_CONTEXT.md` §6.

## Install & run modes

**One install, no git clone, no build, no admin rights.** Installing from npm
ships the API server, the `tasks` CLI, the MCP bridge, the `wft-router`
automation daemon, and the `/tasks:*` skills together — the *same* install backs
every way you might run it.

```bash
npm i -g wood-fired-tasks      # never needs sudo — see the admin-free note below
```

This puts three identical CLI entry points on your PATH — `wood-fired-tasks`,
`tasks`, and the short alias `wft` — plus `wft-router`. Requires **Node ≥ 22**;
works on Linux, macOS, and Windows. (There is no `curl | bash` bootstrap and the
old `install.sh` / `install.ps1` git-clone scripts are retired — npm is the one
supported install path.)

### Pick how to run it

The install is the same everywhere; what differs is *where the database and API
server live*. Pick the row that matches your environment:

| Run mode | Use it when | After installing, run | Guide |
|----------|-------------|-----------------------|-------|
| **Solo / local** | You want a tracker on your own machine, backed by a local SQLite DB. | `wood-fired-tasks setup` → `wood-fired-tasks serve` | [Local setup](docs/SETUP.md#frictionless-install-npm--no-clone) |
| **Background service** | Keep the local API running across logout/reboot (user-scoped, admin-free). | `wood-fired-tasks service install` | [Background service](docs/SETUP.md#background-service-keep-the-server-running) |
| **Remote client** | A shared server already exists — point this machine at it. | `wood-fired-tasks setup --remote  --token wft_pat_…`  *(or `tasks login`)* | [Setup modes](docs/SETUP.md#setup-modes) |
| **Self-hosted server** | Stand up the shared API for a team to point at. | `deploy/install.sh` on the host | [Self-hosting & upgrades](docs/SETUP.md#self-hosting-and-upgrades) |
| **Multi-OS fleet** | Many Windows/Linux/macOS machines on one shared backlog. | self-host once, then `setup --remote` per client | [Multi-OS fleet](docs/SETUP.md#multi-os-client-fleet-one-shared-on-prem-server) |

> **New here? Start with Solo / local** — three commands and the `/tasks:*`
> workflow is live in Claude Code. Nothing is wasted if you move to a shared
> server later: the modes coexist (a Local stdio entry and a Remote bridge entry
> can both live in `~/.claude.json` at once).

### Solo / local — fastest start

After `npm i -g wood-fired-tasks` (above), two commands wire it into Claude Code
and run the server:

```bash
# Merge the local stdio MCP server into ~/.claude.json and copy the /tasks:*
# skills + subagents — idempotent, no manual JSON editing.
wood-fired-tasks setup

# Run the API. Migrates the OS app-data DB on start; listens on 127.0.0.1:3000
# (set HOST=0.0.0.0 to expose on the LAN).
wood-fired-tasks serve
```

Restart Claude Code after `setup` and the `/tasks:*` commands and MCP tools are
live. Then create a project, capture its id, add a task, and list:

```bash
wood-fired-tasks --json project-create --name "My Project"
#  → {"success":true,"data":{"project":{"id":2,...}},"metadata":{"id":2}}
wood-fired-tasks create --title "My first task" --project 2 --created-by "me"
wood-fired-tasks list --project 2
```

> Do NOT assume a project id 1 exists — always create one first and use the id
> it returns.

**Admin-free guarantee.** No step ever escalates: `setup`, `serve`,
`self-update`, and `service install` refuse to shell out to `sudo` / `runas` /
`pkexec` / `doas`. If a global `npm i -g` hits an EACCES on a root-owned npm
prefix, run `wood-fired-tasks setup --fix-npm-prefix` to point npm at a
user-writable prefix (`~/.npm-global`) and re-run **without** sudo. The one and
only path that elevates is the opt-in system-wide service
(`wood-fired-tasks service install --system`); everything else stays in your
user scope.

**Keep it running and up to date.**

```bash
wood-fired-tasks service install   # Linux: user-scoped systemd unit (admin-free)
wood-fired-tasks self-update       # npm i -g @latest + re-sync skills (no sudo)
```

**Point at a shared remote server** (the *Remote client* mode above) with
`wood-fired-tasks setup --remote https://tasks.example.com --token wft_pat_…`: it
writes a URL-only `wood-fired-tasks-remote` MCP entry (proxying every tool to the
REST API) and persists the validated PAT to the CLI credentials file — the same
file `tasks login` writes; the bridge reads its bearer token from there at
runtime, never from `~/.claude.json`. Omit `--token` for the interactive
device-flow / manual-PAT onboarding. Full fleet recipe:
[Multi-OS client fleet](docs/SETUP.md#multi-os-client-fleet-one-shared-on-prem-server).

Browse the bundled guides from anywhere with `wood-fired-tasks docs list` /
`docs show setup`. For detailed setup — local, remote, update, serve, and the
background service — see [docs/SETUP.md](docs/SETUP.md). Working from a clone for
development instead? See [docs/SETUP.md → Development Setup](docs/SETUP.md#development-setup).

## Self-hosting

For self-hosted production deploys (including the fork-and-deploy workflow for OSS operators): provision a host once with `deploy/install.sh`, then ship every subsequent release in place with `deploy/upgrade.sh` (atomic backup, migrate, restart, `/health` probe, manual rollback recipe on failure). The full walkthrough — first-time install, in-place upgrades, deploying your fork, manual rollback, and the migration safety contract — lives at [Self-hosting and upgrades](docs/SETUP.md#self-hosting-and-upgrades). When a deploy or a reboot goes sideways, the [Troubleshooting & Recovery runbook](docs/TROUBLESHOOTING.md) covers boot failures (`exit 78`), wrong/stale-database symptoms, and safe backup/restore.

**Sharing one server across a team.** The common shape is a single on-prem server with a fleet of Windows, Linux, and macOS workstations all pointed at it in remote mode (each client proxies its MCP tool calls to the shared REST API, so everyone sees one backlog). The end-to-end recipe — make the server reachable behind TLS, mint one revocable PAT per machine, and run `wood-fired-tasks setup --remote  --token wft_pat_…` on each OS — is the [Multi-OS client fleet](docs/SETUP.md#multi-os-client-fleet-one-shared-on-prem-server) section.

## Automation (event-driven)

Beyond the REST/CLI/MCP surfaces, an optional **event-router daemon** —
[`wft-router`](packages/wft-router/README.md) — subscribes to the API's SSE
event stream (`GET /api/v1/events`) and dispatches matched task events to
vendor-neutral handlers (`create_task_in_project`, `webhook_post`, `shell_exec`,
`agent_session_dispatch`) per a declarative `triggers.yaml`. It **ships inside
the `wood-fired-tasks` package** — once installed, run it with `wft-router`
(or `npx wft-router`); validate a config with `wft-router --validate
triggers.yaml`. It adds nothing to the core server unless you run it. See the
[design doc](docs/event-router-design.md), the
[automation recipes](docs/automation-recipes/), and the
[reference adapters](examples/adapters/). For agents that just need to block on
a single task unblock, the MCP server also exposes a `wait_for_unblock` tool
(see [docs/MCP.md](docs/MCP.md)).

## Security Model

**Read this before deploying.** Wood Fired Tasks is built for trusted multi-agent coordination. As of **v2.0** the REST API authenticates every `/api/v1` request through a two-strategy chain (`src/api/plugins/auth/index.ts`), tried in order — the first strategy that produces a valid user wins, and that user's id is stamped onto every write (`created_by_user_id`, `assignee_user_id`, …) and the per-request audit log (`user_id`, `token_id`, `auth_method`):

| Order | Strategy | Credential | Wire format |
|-------|----------|------------|-------------|
| 1 | **PAT** — recommended for machines/agents | row in `api_tokens` (SHA-256 hash stored) | `Authorization: Bearer wft_pat_` |
| 2 | **Session** — recommended for humans | OIDC sign-in → sealed-box cookie | `Cookie: wft_session=` |

PATs are minted from a logged-in `/me` web session or offline via `tasks db mint-token`; the raw value is shown **once** at mint time (only a hash is stored) and revoked via the `/me` UI, `DELETE /me/tokens/:id`, or `tasks logout`. Sessions come from OIDC (`/auth/login` → provider → `/auth/callback`, protected by PKCE + state), are sealed-box-encrypted with `SESSION_COOKIE_SECRET`, and expire after 8h. The CLI and remote MCP client send the PAT as `Authorization: Bearer`. Full detail: [SECURITY.md → Authentication Architecture](SECURITY.md#authentication-architecture).

### ⚠️ Authentication is NOT authorization — every identity is admin

**Read this before exposing the service to anything but trusted callers.**

- **Authentication ≠ authorization.** The auth chain only *identifies* the caller; it does **not** scope what they may do.
- **Every authenticated identity is effectively an admin.** Any valid credential — PAT or OIDC session — can read, write, and delete **every** task, project, comment, and dependency across **every** project in the database.
- **There is NO RBAC, NO ACL, and NO per-project / per-tenant isolation.** These are not implemented; scoped/role-based permissions are tracked only as future work.
- **Do NOT expose this service on a public network, and do NOT run it multi-tenant, without an external authorization layer** (e.g. an authenticating reverse proxy that enforces its own per-tenant access control in front of the API). Treat any issued credential as full admin access to all data.

### Legacy `X-API-Key` was removed in v2.0

The legacy `X-API-Key` shared-secret strategy was **removed entirely in v2.0** (`src/api/plugins/auth/index.ts` no longer accepts it). A request carrying only `X-API-Key` now gets **401**. `API_KEYS` is no longer an auth method and is **not** a required env var — it is not in the Zod env schema. If set, it only (optionally) seeds inert legacy `users` rows (`is_legacy=1`) for display/back-reference; those rows hold no usable credential. Every deployment must now issue **PATs** — one per machine/agent, so you can revoke an individual token without disturbing others — or use OIDC sessions. PATs are minted from a `/me` web session or offline via `tasks db mint-token`. See [SECURITY.md → Authentication Architecture](SECURITY.md#authentication-architecture) and `tasks db migrate-identities` for the migration path off legacy keys.

### Defense in depth

Auth is paired with two configurable protections, both mitigations rather than authorization:

- **Rate limiting** via `@fastify/rate-limit` (global, 1000

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Wood-Fired-Games](https://github.com/Wood-Fired-Games)
- **Source:** [Wood-Fired-Games/wood-fired-tasks](https://github.com/Wood-Fired-Games/wood-fired-tasks)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/wood-fired-tasks

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-wood-fired-games-wood-fired-tasks
- Seller: https://agentstack.voostack.com/s/wood-fired-games
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.