Taskswarm

TaskSwarm

[CI] [npm version] [License: MIT] [PyPI version]

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.

[Installing taskswarm-cli from npm, checking its version, then starting the TaskSwarm server and seeing the live status page URL it prints]

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-clitaskswarm 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-clitaskswarm 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 servernode dist/cli.js start# TaskSwarm server listening on http://127.0.0.1:4173# Live status page: http://127.0.0.1:4173/?token=<your-token>
# Terminal 2: report a session's status as it worksnode dist/cli.js agent report-status --task my-fix --repo ./api --state runningnode 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.

[Running taskswarm hooks install claude-code and inspecting the Stop/Notification entries it writes into .claude/settings.json]

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 ./apinode dist/cli.js task list

[Adding two tasks with taskswarm task add, then listing them with taskswarm task list in human-readable and --json form]

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 <id> --repo <path> --state <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 <command> --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 boguserror: option '--state <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 blockedError: 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): AgentEvent -- fills in event_id/timestamp/schema_version defaults
• AGENT_TYPES, AGENT_STATUSES -- the const arrays backing the AgentType/AgentStatus union types
• NOTIFY_ON_STATUSES: ReadonlySet<AgentStatus> -- the four statuses that trigger a notification: blocked, needs-review, failed, done
• CURRENT_SCHEMA_VERSION -- the current envelope version number

Server (src/server/)

• class EventStore extends EventEmitter -- in-memory session store backed by an append-only JSONL log. constructor(logPath?: string, options?: EventStoreOptions). Methods: append(event): { previousStatus, previousBlockedReason }, getSession(sessionId): SessionState | undefined, listSessions(): SessionState[], size(): number. Emits 'event' on every append.
• startServer(options?: StartServerOptions): Promise<RunningServer> -- boots the event store and the HTTP/SSE server. RunningServer is { server, store, config, url, close }.
• loadOrCreateConfig(): TaskSwarmConfig, saveConfig(config): void, rotateToken(): string, generateToken(): string, getTaskSwarmHome(): string

Notifications (src/notify/index.ts)

• shouldNotify(status, previousStatus, blockedReason?, previousBlockedReason?): boolean -- the dedup rule. Keys on the (status, blocked_reason) pair, not status alone, so two different permission prompts in a row both notify.
• notify(event, previousStatus, previousBlockedReason, options?: NotifyOptions): void -- fires the enabled channels. Local OS notification is always on; ntfy.sh only fires when options.ntfy.enabled is true.

Adapters (src/adapters/)

• interface AgentAdapter { agentType: AgentType; name: string; toEventInput(raw): AgentEventInput } -- the plugin point every integration implements
• class GenericAdapter implements AgentAdapter -- the wrapper-script fallback path
• class ClaudeCodeAdapter implements AgentAdapter, installClaudeCodeHooks(options: InstallHooksOptions): InstallHooksResult -- the real Claude Code hooks integration

Embedding the server directly instead of running taskswarm start, verified working against the built package:

import { startServer, EventStore } from 'taskswarm-cli';
const running = await startServer({ logPath: null }); // in-memory only, no JSONL logconsole.log(running.url); // http://127.0.0.1:4173/?token=...console.log(running.store instanceof EventStore); // trueawait running.close();

Types exported alongside every function: AgentEvent, AgentEventInput, AgentType, AgentStatus, SessionState, TaskSwarmConfig, NotifyOptions, RunningServer, StartServerOptions, HookInstallScope, InstallHooksOptions, InstallHooksResult.

The Python distribution mirrors the same surface (snake_case instead of camelCase, py.typed for type checkers), also verified working against the built package:

from taskswarm import start_server, EventStore, TaskSwarmConfig
cfg = TaskSwarmConfig(token="local-dev", port=4175, host="127.0.0.1", ntfy={"enabled": False})running = start_server(config=cfg, log_path=None)  # in-memory only, no JSONL logprint(running.url)  # http://127.0.0.1:4175/?token=local-devrunning.close()

MCP Server

TaskSwarm's Python distribution ships a Model Context Protocol server, so an MCP-compatible agent (Claude Desktop, Claude Code, an orchestrator) can call TaskSwarm directly as a tool instead of shelling out to the CLI and parsing text.

pip install "taskswarm-cli[mcp]"

It exposes one tool, run, a generic subprocess wrapper: pass it the same argument list you'd pass on the command line, and it shells out to the installed taskswarm binary, parses the resulting JSON, and returns it. Every failure mode (missing binary, launch error, timeout, non-zero exit, unparseable output) comes back as a plain {"error": ...} dict instead of raising, so a bad call can't crash the server.

run(args=["task", "list", "--json"])# -> {"result": [{"id": "84c94aca-...", "title": "Fix flaky test", "repo": "/tmp/x", "created_at": "2026-08-09T17:37:00.949Z", "status": "unknown"}]}

To register it with an MCP-compatible client such as Claude Desktop, add it to the client's server config:

{  "mcpServers": {    "taskswarm": {      "command": "taskswarm-mcp"    }  }}

This assumes taskswarm-mcp is already on PATH (installed via the mcp extra above). If you installed it somewhere else, replace "command" with the full path to the console script. This server is currently Python-only; the npm distribution does not yet ship an MCP server.

How it compares

Verified live against each project's GitHub API metadata and README, 2026-08-03. TaskSwarm's own numbers are measured, not estimated. Methodology below the table.

TaskSwarm isn't trying to out-board any of these three. paperclip and Multica are built for running a whole roster of agents like an org chart, and Vibe Kanban (while it lasted) was a full planning-and-review workspace. TaskSwarm stays narrow: the one thing none of the three ship is a push signal when a session needs you, and that's the whole product here.

Benchmark methodology (so you can reproduce it): measured on macOS 26.5.1, Apple Silicon (arm64), Node v24.4.0, npm 11.15.0, 2026-07-15.

• Cold start: process launch to a curl receiving HTTP 200 from the live status page URL, timed with time.perf_counter(), averaged across repeated runs (158 to 188 ms observed).
• Idle memory: ps -o rss on the running node dist/cli.js start process, a few seconds after boot with no active sessions (38.4 to 39.4 MB observed across runs).
• Event-ingestion-to-notification-dispatch latency: wall-clock time for a POST /events request to return 201, over 20 requests with status: blocked (the code path that synchronously calls notify(), which spawns the OS notification process, before the HTTP response is sent). Median 3.1 ms, mean 5.8 ms, p95 24.1 ms, n=20.
• Total time-to-first-board (a real first-time user, fresh git clone): npm install (2.05 s) plus npm run build (0.78 s) plus start to live page reachable (0.15 s), totaling 2.99 s, on a machine with a warm local npm cache. Target was under 60 seconds; actual measured result is roughly 20x under that.

Numbers not listed for the other three tools are not estimated placeholders. They are genuinely not measured, because running their full stacks (Rust, PostgreSQL, Docker Compose) wasn't in scope for this pass. Their star counts, license terms, and maintenance status above are verified live facts, not benchmarks.

Where TaskSwarm sits in the wider 2026 field

paperclip, Vibe Kanban, and Multica are the closest full-board comparables, but they're not the whole picture. Running several coding agents in parallel became one of the most active corners of open source in 2026: Anthropic's own 2026 Agentic Coding Trends Report names multi-agent coordination as one of eight trends reshaping how software gets built, and OpenAI reported Codex alone crossed 5 million weekly users by June 2026. A whole wave of orchestration UIs shipped alongside that growth. Here's where TaskSwarm sits next to the newer parallel-agent tools that cover a similar workflow with a different shape, verified live 2026-08-03:

Every one of these gives you somewhere to watch your agents work. TaskSwarm is built on the opposite assumption: you're not watching, so it pushes to you instead. Adjacent to this, the standardized agent-integration protocol MCP grew into its own mainstream category over the same period, 10,000+ active public MCP servers and 97M+ monthly SDK downloads as of Anthropic's December 2025 ecosystem update -- the same underlying shift toward agents that plug into standard integration points, which is the same reason TaskSwarm's own wrapper-script adapter (taskswarm agent report-status) is deliberately protocol-agnostic rather than tied to one agent's hook format.

What TaskSwarm is, and why it exists

Running one coding agent is a conversation. Running three or four in parallel turns into a tab-switching problem: nothing pushes state to you, so you end up polling terminals by eye just to find out one of them has been sitting on a permission prompt for ten minutes. TaskSwarm exists to close that gap: a push signal for the moment a session actually needs a human.

The core (event server, CLI, live status page, Claude Code hook integration) is MIT-licensed and free to self-host, for individual use, for a team, for anything. There is no hosted tier and no paid tier shipped currently. The self-hosted core is the entire product right now.

FAQ

Does this replace my Kanban board / Linear / GitHub Projects? No. Those track work items a human plans. TaskSwarm tracks live agent session state and tells you the instant it changes. Different job.

Do I need Claude Code specifically? No. taskswarm hooks install claude-code is the one verified native integration currently shipped. Codex, Cursor, or anything else works through the same primitive that adapter calls internally: taskswarm agent report-status, callable from any wrapper script around any CLI agent.

Where does my data go? Nowhere, by default. The server binds to 127.0.0.1, requires a bearer token for every request, and writes state to ~/.taskswarm/ (or wherever TASKSWARM_HOME points) on your own disk. The only optional channel that leaves your machine is ntfy.sh, and it's off unless you explicitly enable it.

Is this going to start charging me later? The MIT-licensed core stays free. Everything described in this README is the whole product as it exists today, not a trial or a limited tier of something bigger.

Why not just use tmux and watch the panes? That's the status quo this project is a response to. It works until you're running more than two or three sessions at once, at which point you're spending more time polling panes than writing code.

What happens if the server isn't running when I call a command? Commands that need it fail fast with a specific message (could not reach TaskSwarm server at http://127.0.0.1:4173 -- is it running? (taskswarm start)), not a stack trace. task add and task list still work without the server; they just skip live-status enrichment.

What is TaskSwarm, exactly? A self-hosted event server plus a CLI. Agent sessions, or a wrapper script around any agent, report status to it (taskswarm agent report-status), and it pushes a local OS notification and updates a live SSE status page the instant a session goes blocked, needs-review, failed, or done. It doesn't launch, schedule, or run agents itself; it only tracks and pushes state for sessions that are already running somewhere else.

Can I use TaskSwarm as a library instead of the CLI? Yes. Both distributions export a real programmatic surface, not just a bin entry: import { startServer, EventStore } from 'taskswarm-cli' on npm, from taskswarm import start_server, EventStore on PyPI. See the Library API reference above for the full export list and a working example of each.

What are the platform and install requirements? The npm build (taskswarm-cli) needs Node.js >=18.18.0, per the engines field in package.json. The PyPI build (also taskswarm-cli) needs Python >=3.9, per pyproject.toml, which also declares Operating System :: OS Independent. One caveat that's platform-specific in practice: the native OS push notification only fires on macOS, via osascript (see src/notify/os-notify.ts). 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.

How does TaskSwarm compare to a specific competitor, like Vibe Kanban or paperclip? See the comparison tables above for the full breakdown, but the short version: paperclip and Multica are built to run and visualize a whole roster of agents like an org chart, and Vibe Kanban was a full planning-and-review workspace before the company behind it shut down (its README carries a shutdown banner as of this writing). None of the three list a push/desktop notification feature in their own README. TaskSwarm skips the board entirely and only does the one thing: push a signal the instant a session needs you.

Can I use TaskSwarm in a commercial or paid product? Yes. The core (event server, CLI, live status page, Claude Code hook integration) is MIT-licensed with no field-of-use restriction, so self-hosting it inside a commercial product, a paid service, or an internal tool is fine. That's a real point of difference from Multica in the comparison table above, which ships under a modified Apache-2.0 license that explicitly restricts hosted commercial use.

Contributing

Issues and pull requests are welcome. Before opening a PR:

npm run lintnpm run typechecknpm run test:coverage

All three must pass clean. For the Python distribution, cd python && pip install -e ".[dev]" && pytest. See CONTRIBUTING.md for the full checklist covering both codebases.

License

MIT. See LICENSE. Free to self-host, modify, and redistribute, individually or as a team. No hosted or paid tier exists in this version.