` (required), `--repo <path>` (required), `--json` | | `taskswarm task list` | List tracked tasks, enriched with live status when the server is reachable | `--json` | | `taskswarm agent report-status` | Report a status transition for a task/session to the local server | `--task <id>` (required), `--repo <path>` (required), `--state <state>` (required, one of `queued\|running\|blocked\|needs-review\|done\|failed`), `--blocked-reason <text>`, `--agent-type <type>` (`claude-code\|codex\|cursor\|generic`, default `generic`), `--json` | | `taskswarm token rotate` | Generate a new bearer token, invalidating the old one | `--json` | | `taskswarm hooks install <adapter>` | Install hooks for an agent integration (currently `claude-code`) | `--scope <project\|local\|user>` (default `project`), `--project-dir <path>`, `--json` | | `taskswarm hooks claude-code-relay` | Internal: reads a hook payload from stdin and relays it. Installed automatically; not meant to be run by hand. | none | 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 <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): 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: ```ts import { startServer, EventStore } from 'taskswarm-cli'; const running = await startServer({ logPath: null }); // in-memory only, no JSONL log console.log(running.url); // http://127.0.0.1:4173/?token=... console.log(running.store instanceof EventStore); // true await 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: ```python 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 log print(running.url) # http://127.0.0.1:4175/?token=local-dev running.close() ``` ## MCP Server TaskSwarm's **Python distribution** ships a [Model Context Protocol](https://modelcontextprotocol.io) 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. ```bash 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. ```python 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: ```json { "mcpServers": { "taskswarm": { "command": "taskswarm-mcp" } } } ```</article></body></html>

{ "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: ```bash 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](./docs/hooks-install.gif) Locally track tasks independent of live session state (a lightweight to-do list, not the event feed): ```bash node dist/cli.js task add --title "Fix flaky test" --repo ./api node 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](./docs/usage.gif) ## 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`): | Command | Description | Key options | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `taskswarm start` | Start the TaskSwarm server and print the live status page URL | `--json` | | `taskswarm task add` | Register a new task | `--title ` (required), `--repo <path>` (required), `--json` | | `taskswarm task list` | List tracked tasks, enriched with live status when the server is reachable | `--json` | | `taskswarm agent report-status` | Report a status transition for a task/session to the local server | `--task <id>` (required), `--repo <path>` (required), `--state <state>` (required, one of `queued\|running\|blocked\|needs-review\|done\|failed`), `--blocked-reason <text>`, `--agent-type <type>` (`claude-code\|codex\|cursor\|generic`, default `generic`), `--json` | | `taskswarm token rotate` | Generate a new bearer token, invalidating the old one | `--json` | | `taskswarm hooks install <adapter>` | Install hooks for an agent integration (currently `claude-code`) | `--scope <project\|local\|user>` (default `project`), `--project-dir <path>`, `--json` | | `taskswarm hooks claude-code-relay` | Internal: reads a hook payload from stdin and relays it. Installed automatically; not meant to be run by hand. | none | 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 <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): 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: ```ts import { startServer, EventStore } from 'taskswarm-cli'; const running = await startServer({ logPath: null }); // in-memory only, no JSONL log console.log(running.url); // http://127.0.0.1:4173/?token=... console.log(running.store instanceof EventStore); // true await 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: ```python 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 log print(running.url) # http://127.0.0.1:4175/?token=local-dev running.close() ``` ## MCP Server TaskSwarm's **Python distribution** ships a [Model Context Protocol](https://modelcontextprotocol.io) 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. ```bash 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. ```python 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: ```json { "mcpServers": { "taskswarm": { "command": "taskswarm-mcp" } } } ```</article></body></html>

taskswarm

Installation