Taskswarm

TaskSwarm

Install • Quickstart • What it does • CLI reference • MCP Server • How it compares • FAQ

Self-hosted event server and CLI that fires a local OS notification and updates a live status page the instant a parallel coding-agent session blocks, needs review, fails, or finishes.

You're running three Claude Code sessions across two repos. One of them hit a permission prompt four minutes ago and has been sitting there ever since, waiting on you. You didn't know, because nothing told you. You just tabbed back to check.

TaskSwarm is a self-hosted event server that fixes that. Every agent session reports its state, and the instant one goes blocked, needs review, fails, or finishes, TaskSwarm fires a local OS notification and updates a live status page. No polling terminals. No account. No cloud dependency.

Install

TaskSwarm ships as two independent, equally first-class distributions of the same event server -- an npm package (this codebase, TypeScript) and a PyPI package (taskswarm-cli, Python, python/). Pick whichever fits your toolchain; the server and CLI don't need to be the same distribution as whatever agent you're reporting from.

npm (JS/TS): live on npm as taskswarm-cli:

npm install -g taskswarm-cli

taskswarm start

Prefer not to install globally? npx taskswarm-cli start runs the same binary with no install step.

pip (Python): live on PyPI as taskswarm-cli (renamed from the original taskswarm package, which has stopped receiving updates and points here):

pip install taskswarm-cli

taskswarm start

See python/README.md for the Python-specific guide. Both distributions speak the same wire protocol (the same event schema, the same notification-dedup rule), so a Python-started server and an npm CLI reporting into it (or vice versa) work together without issue.

Quickstart

# Terminal 1: start the server

node dist/cli.js start

TaskSwarm server listening on http://127.0.0.1:4173

Live status page: http://127.0.0.1:4173/?token=

Terminal 2: report a session's status as it works

node dist/cli.js agent report-status --task my-fix --repo ./api --state running node dist/cli.js agent report-status --task my-fix --repo ./api --state done

Open the live status page URL printed by start. The row for my-fix updates the instant each report-status call lands, no refresh. This is the actual output from that flow, captured while writing this README:

{

"sessions": [ { "session_id": "my-fix", "latest": { "repo": "./api", "agent_type": "generic", "status": "done", "...": "..." }, "history": [ { "status": "running", "timestamp": "2026-07-15T23:46:41.376Z" }, { "status": "done", "timestamp": "2026-07-15T23:46:41.436Z" } ] } ] }

Wire it into Claude Code directly instead of calling report-status by hand:

node dist/cli.js hooks install claude-code

This writes Stop/Notification hooks into .claude/settings.json for the current project. Every turn Claude Code finishes, and every permission prompt or idle wait it surfaces, now reports into TaskSwarm automatically.

Locally track tasks independent of live session state (a lightweight to-do list, not the event feed):

node dist/cli.js task add --title "Fix flaky test" --repo ./api

node dist/cli.js task list

What it does

• Push notifications, from a board you don't have to keep open. The moment a session transitions to blocked, needs-review, failed, or done, TaskSwarm fires a native OS notification (osascript on macOS, a terminal bell fallback elsewhere). Measured dispatch latency below. None of paperclip, Vibe Kanban, or Multica (see comparison below) do this; all three are boards you have to be looking at.
• A live status page that updates over server-sent events, not polling. One flat table: session, repo, agent type, status, last-event timestamp. No refresh button.
• Real Claude Code hook integration, verified against the published hooks reference. taskswarm hooks install claude-code writes Stop and Notification hook entries into .claude/settings.json, pointed at the exact Node binary and CLI script already on disk. It deliberately avoids npx; see the code comment in src/adapters/claude-code-adapter.ts for why floating registry resolution on every hook fire is a supply-chain risk. One caveat stated plainly: Claude Code's Stop hook fires per-turn, not per-task, so a long multi-turn session currently reports done after every turn, not just the final one.
• A wrapper-script fallback for Codex, Cursor, or anything else. taskswarm agent report-status --task --repo --state is the same primitive the Claude Code adapter calls under the hood. Any script wrapping any CLI agent can call it directly.
• A bearer-token-gated local API, bound to loopback by default. POST /events and the live page both require the token TaskSwarm generates on first run (~/.taskswarm/config.json, written 0600). Rotate it with taskswarm token rotate.
• Agent-native by design. Every subcommand ships a --json flag with a stable schema, including error output, so a script calling this CLI never has to scrape human-formatted text.
• ntfy.sh is opt-in, never default. The only notification channel that leaves your machine, and it's off unless you turn it on. The self-hosted claim holds end to end without it.

[!NOTE]

The native OS push notification only fires on macOS, via osascript. On Linux and Windows, TaskSwarm falls back to a console line plus a terminal bell instead of a system notification, still local, still without ntfy.sh unless you opt in.

CLI reference

Captured directly from --help output on the built CLI (node dist/cli.js --help):

Every subcommand also takes -h, --help. taskswarm --version prints the installed package's own version number, read live from package.json (so it always matches whatever release you actually have installed, rather than a fixed number that would go stale here).

A real failure, for reference

$ node dist/cli.js agent report-status --task foo --repo /tmp/x --state bogus

error: option '--state ' argument 'bogus' is invalid. Allowed choices are queued, running, blocked, needs-review, done, failed.

$ node dist/cli.js agent report-status --task foo --repo /tmp/x --state blocked Error: could not reach TaskSwarm server at http://127.0.0.1:4173 -- is it running? (taskswarm start)

Both exit non-zero with a plain-English message and no stack trace, including under --json.

Library API reference

The npm package is also importable, not just runnable as a CLI: main/types point at dist/index.js/dist/index.d.ts, and src/index.ts exports a real public surface for anything that wants to embed the event store, server, or adapters directly instead of shelling out.

Schema (src/schema/events.ts)

• agentEventSchema, agentEventInputSchema -- Zod schemas for the event envelope
• `toAgentEvent(input: AgentEventInput):