Wood Fired Tasks

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/USAGEPATTERNS.md](docs/USAGEPATTERNS.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/AGENTCONTEXT.md](docs/AGENTCONTEXT.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.

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:

# 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:

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.

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
• Source: 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.