Taskswarm MCP server

<!-- mcp-name: io.github.RudrenduPaul/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=<your-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.

Shortened. The full README is on GitHub.