taskswarm

TaskSwarm

安装 • 快速开始 • 功能介绍 • CLI 参考 • MCP 服务 • 对比 • 常见问题

可自托管的事件服务和 CLI：当并行编码 Agent 会话阻塞、需要审核、失败或完成时，立即触发本地操作系统通知并更新实时状态页。

你正在两个代码仓库中运行三个 Claude Code 会话。其中一个会话在四分钟前遇到了权限提示，此后一直停在那里等你处理。你却毫不知情，因为没有任何通知告诉你。你只能切回去查看。

TaskSwarm 是一个可自托管的事件服务，可以解决这个问题。每个 Agent 会话都会报告自己的状态；一旦某个会话阻塞、需要审核、失败或完成，TaskSwarm 就会立即触发本地操作系统通知并更新实时状态页。无需轮询终端。无需账号。无需依赖云服务。

安装

TaskSwarm 提供两个相互独立、地位同等的一流发行版本， 使用的是同一个事件服务——npm 包（此代码库，TypeScript）和 PyPI 包（taskswarm-cli，Python，python/）。选择适合你工具链的版本； 服务和 CLI 无需与报告状态的 Agent 使用相同的发行版本。

npm（JS/TS）： 可在 npm 上获取，包名为 taskswarm-cli：

npm install -g taskswarm-cli
taskswarm start

不想全局安装？运行 npx taskswarm-cli start 即可使用同一个 二进制文件，无需安装。

pip（Python）： 可在 PyPI 上获取，包名为 taskswarm-cli（原 taskswarm 包已停止更新，并指向此处）：

pip install taskswarm-cli
taskswarm start

Python 专属指南请参阅 python/README.md。两个 发行版本使用相同的线协议（相同的事件架构， 相同的通知去重规则），因此由 Python 启动的服务和向其报告状态的 npm CLI （反之亦然）可以协同工作，不会出现问题。

快速开始

# 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

打开 start 打印的实时状态页 URL。每次 report-status 调用到达时， my-fix 对应的行都会立即更新，无需刷新。以下是编写本 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" }
      ]
    }
  ]
}

可将其直接接入 Claude Code，而不是手动调用 report-status：

node dist/cli.js hooks install claude-code

这会将 Stop/Notification 钩子写入当前项目的 .claude/settings.json。 每当 Claude Code 完成一轮对话，或出现权限提示或空闲等待时， 都会自动向 TaskSwarm 报告状态。

在本地跟踪独立于实时会话状态的任务（轻量级待办事项列表，而非事件流）：

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

功能

• 无需一直打开看板，也能接收推送通知。 会话一旦转换为 blocked、needs-review、failed 或 done，TaskSwarm 就会触发原生操作系统通知（macOS 上使用 osascript，其他系统则回退为终端响铃）。下文列出了实测派发延迟。paperclip、Vibe Kanban 和 Multica（参见下文对比）都不支持此功能；使用这三款工具时，你必须一直盯着看板。
• 实时状态页面通过服务器发送事件更新，而非轮询。 页面显示一个简单的表格，列出会话、仓库、Agent 类型、状态和上次事件时间戳，无需点击刷新。
• 真正的 Claude Code 钩子集成，并已依据公开的钩子参考文档验证。 taskswarm hooks install claude-code 会将 Stop 和 Notification 钩子条目写入 .claude/settings.json，并指向磁盘上已有的确切 Node 二进制文件和 CLI 脚本。它会刻意避开 npx；关于每次触发钩子时都从注册表动态解析版本为何存在供应链风险，请参阅 src/adapters/claude-code-adapter.ts 中的代码注释。明确说明一项限制：Claude Code 的 Stop 钩子会在每轮对话后触发，而非每项任务结束后触发，因此目前长时间的多轮会话会在每轮后报告 done，而不只是最终一轮。
• 适用于 Codex、Cursor 或其他工具的包装脚本回退方案。 taskswarm agent report-status --task <id> --repo <path> --state <state> 是 Claude Code 适配器在底层调用的同一基本操作。任何包装了任意 CLI Agent 的脚本都可以直接调用它。
• 由 Bearer Token 保护的本地 API，默认绑定到回环地址。 POST /events 和实时页面都需要 TaskSwarm 首次运行时生成的令牌（~/.taskswarm/config.json，以 0600 权限写入）。使用 taskswarm token rotate 可轮换令牌。
• 专为 Agent 设计。 每个子命令都提供带有稳定架构的 --json 标志，包括错误输出，因此调用此 CLI 的脚本无需解析面向人类的文本。
• ntfy.sh 为可选项，绝不会默认启用。 这是唯一会将通知发送出你设备的渠道，除非你主动启用，否则该渠道处于关闭状态。即使不启用它，也能从始至终实现可自托管。

说明

原生操作系统推送通知仅在 macOS 上通过 osascript 触发。在 Linux 和 Windows 上，TaskSwarm 会回退为输出一行控制台文本并响起终端提示音，而非发送系统通知；这些操作仍在本地进行，除非你主动启用 ntfy.sh，否则不会使用它。

CLI 参考

直接从构建后的 CLI 的 --help 输出中获取（node dist/cli.js <command> --help）：

命令	描述	关键选项
taskswarm start	启动 TaskSwarm 服务并打印实时状态页面 URL	--json
taskswarm task add	注册新任务	--title <title>（必填）、--repo <path>（必填）、--json
taskswarm task list	列出已跟踪的任务；服务可访问时会附加实时状态	--json
taskswarm agent report-status	向本地服务报告任务／会话的状态转换	--task <id>（必填）、--repo <path>（必填）、--state <state>（必填，取值为 queued|running|blocked|needs-review|done|failed 之一）、--blocked-reason <text>、--agent-type <type>（claude-code|codex|cursor|generic，默认值为 generic）、--json
taskswarm token rotate	生成新的 bearer token，并使旧令牌失效	--json
taskswarm hooks install <adapter>	为 Agent 集成安装钩子（目前支持 claude-code）	--scope <project|local|user>（默认值为 project）、--project-dir <path>、--json
taskswarm hooks claude-code-relay	内部命令：从 stdin 读取钩子负载并进行转发。会自动安装；不应手动运行。	无
每个子命令也都支持 -h, --help。taskswarm --version 会从 package.json 实时读取已安装软件包自身的版本号并打印出来（因此它始终与实际安装的版本一致，而不是使用一个会很快过时的固定版本号）。

一个真实的失败示例，供参考

$ 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`)

两者都会以非零状态码退出，并显示一条通俗易懂的消息，不会输出堆栈跟踪；即使使用 --json 也是如此。

库 API 参考

这个 npm 软件包也可以导入使用，而不只是作为 CLI 运行：main/types 指向 dist/index.js/dist/index.d.ts，并且 src/index.ts 导出了实际的公共接口，供需要直接嵌入事件存储、服务或适配器，而不是通过 shell 调用的项目使用。

架构（src/schema/events.ts）

• agentEventSchema、agentEventInputSchema —— 事件封装的 Zod 架构
• toAgentEvent(input: AgentEventInput): AgentEvent —— 填充 event_id/timestamp/schema_version 默认值
• AGENT_TYPES、AGENT_STATUSES —— 支撑 AgentType/AgentStatus 联合类型的常量数组
• NOTIFY_ON_STATUSES: ReadonlySet<AgentStatus> —— 会触发通知的四种状态：blocked、needs-review、failed、done
• CURRENT_SCHEMA_VERSION —— 当前封装版本号

服务（src/server/）

• class EventStore extends EventEmitter —— 基于仅追加 JSONL 日志的内存会话存储。constructor(logPath?: string, options?: EventStoreOptions)。方法：append(event): { previousStatus, previousBlockedReason }、getSession(sessionId): SessionState | undefined、listSessions(): SessionState[]、size(): number。每次追加都会触发 'event'。
• startServer(options?: StartServerOptions): Promise<RunningServer> —— 启动事件存储以及 HTTP/SSE 服务。RunningServer 为 { server, store, config, url, close }。
• loadOrCreateConfig(): TaskSwarmConfig、saveConfig(config): void、rotateToken(): string、generateToken(): string、getTaskSwarmHome(): string

通知（src/notify/index.ts）

• shouldNotify(status, previousStatus, blockedReason?, previousBlockedReason?): boolean —— 去重规则。依据 (status, blocked_reason) 配对，而非仅依据状态，因此连续出现两个不同的权限提示时都会通知。
• notify(event, previousStatus, previousBlockedReason, options?: NotifyOptions): void —— 触发已启用的渠道。本地操作系统通知始终开启；只有当 options.ntfy.enabled 为 true 时才会触发 ntfy.sh 通知。

适配器（src/adapters/）

• interface AgentAdapter { agentType: AgentType; name: string; toEventInput(raw): AgentEventInput } —— 每个集成都要实现的插件接口
• class GenericAdapter implements AgentAdapter —— 包装脚本回退路径
• class ClaudeCodeAdapter implements AgentAdapter、installClaudeCodeHooks(options: InstallHooksOptions): InstallHooksResult —— 真正的 Claude Code hooks 集成

无需运行 taskswarm start，直接嵌入服务；已在构建后的软件包上验证可正常工作：

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();

每个函数还会同时导出以下类型：AgentEvent、AgentEventInput、AgentType、AgentStatus、SessionState、TaskSwarmConfig、NotifyOptions、RunningServer、StartServerOptions、HookInstallScope、InstallHooksOptions、InstallHooksResult。

Python 发行包提供相同的接口（使用 snake_case，而非 camelCase，并包含供类型检查器使用的 py.typed），也已在构建后的软件包上验证可正常工作：

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 服务

TaskSwarm 的 Python 发行包附带一个 Model Context Protocol 服务，因此，兼容 MCP 的 Agent（Claude Desktop、Claude Code、编排器）可以直接将 TaskSwarm 作为工具调用，而无需通过命令行调用 shell 并解析文本。

pip install "taskswarm-cli[mcp]"

它公开了一个工具 run，这是一个通用的子进程包装器：传入与命令行中相同的参数列表，它会调用已安装的 taskswarm 二进制文件、解析生成的 JSON 并返回结果。所有失败情况（缺少二进制文件、启动错误、超时、退出码非零、输出无法解析）都会以普通的 {"error": ...} 字典返回，而不会抛出异常，因此错误调用不会导致服务崩溃。

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"}]}

要将其注册到兼容 MCP 的客户端（例如 Claude Desktop），请将其添加到客户端的服务配置中：

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

这假设 taskswarm-mcp 已在 PATH 中（通过上面的 mcp extra 安装）。如果你将其安装在其他位置，请将 "command" 替换为控制台脚本的完整路径。目前此服务仅支持 Python；npm 发行包尚未附带 MCP 服务。

对比

截至 2026-08-03，已根据各项目的 GitHub API 元数据和 README 完成实时验证。TaskSwarm 自身的数据是实测值，而非估算值。表格下方介绍了方法。

	TaskSwarm	paperclip	Vibe Kanban	Multica
星标	尚未发布	75,547	27,656	43,690
许可证	MIT	MIT	Apache-2.0	源码可用（修改版 Apache-2.0；限制托管式商业用途）
维护状态	活跃	活跃（今天有提交）	即将停止维护：公司已关闭，README 中有关闭公告，最后一次提交于 2026-04-24，截至本文撰写时已超过 3 个月未更新	活跃（今天有提交）
状态变化时推送／桌面通知	支持：默认发送本地 OS 通知，可选择启用 ntfy.sh	README 中未提及	README 中未提及	README 中未提及
主要界面	实时状态表（SSE）	完整的看板 + 组织结构图	完整的看板	完整的看板
可自托管，无需账户	支持	支持	支持（自托管指南、Docker）	支持（Docker）
空闲内存占用	约 39 MB（实测）	未测量（不在范围内）	未测量（不在范围内）	未测量（不在范围内）
冷启动（服务器启动到可访问）	约 0.19 s（实测）	未测量	未测量	未测量
TaskSwarm 并不打算在看板功能上胜过这三者。paperclip 和 Multica 面向像组织架构图一样运行一整组 Agent，而 Vibe Kanban（在它还存在时）则是一个完整的规划与审查工作区。TaskSwarm 专注于一个小范围：这三者都没有提供的，是会话需要你处理时发出的推送信号，而这正是本产品的全部定位。

基准测试方法（便于复现）：测试环境为 macOS 26.5.1、Apple Silicon（arm64）、Node v24.4.0、npm 11.15.0，测试日期为 2026-07-15。

• 冷启动：从进程启动到 curl 收到实时状态页 URL 返回的 HTTP 200 响应所需时间，使用 time.perf_counter() 计时，并对多次运行结果取平均值（观察到的范围为 158 至 188 ms）。
• 空闲内存：运行中的 node dist/cli.js start 进程启动几秒后、没有活跃会话时，通过 ps -o rss 测得（多次运行观察到的范围为 38.4 至 39.4 MB）。
• 事件接收到通知派发的延迟：POST /events 请求返回 201 所需的墙钟时间；共测试 20 个 status: blocked 请求（此代码路径会在发送 HTTP 响应前同步调用 notify()，后者会启动操作系统通知进程）。中位数为 3.1 ms，平均值为 5.8 ms，p95 为 24.1 ms，n=20。
• 从零到首个看板的总耗时（真实的新用户，使用全新 git clone）：npm install（2.05 s）加上 npm run build（0.78 s），再加上从 start 到页面可访问所需的时间（0.15 s），总计 2.99 s；测试机器的本地 npm 缓存已预热。目标是低于 60 秒；实际测得的结果约快 20 倍。

其他三个工具未列出的数字并非估算值或占位符，而是确实没有测量，因为本轮测试不在范围内的，是运行它们的完整技术栈（Rust、PostgreSQL、Docker Compose）。上文所列的 Star 数、许可证条款和维护状态均为实时核实的信息，并非基准测试结果。

TaskSwarm 在 2026 年更广阔的领域中的定位

paperclip、Vibe Kanban 和 Multica 是最接近的完整看板类对比项目，但并非全部。2026 年，并行运行多个编码 Agent 成为开源领域最活跃的方向之一：Anthropic 自己的 2026 Agentic Coding Trends Report 将多 Agent 协调列为重塑软件构建方式的八大趋势之一，而 OpenAI 报告称，仅 Codex 的每周用户数就突破了 500 万（截至 2026 年 6 月）。伴随这股增长浪潮，各类编排 UI 也纷纷推出。以下是 TaskSwarm 与工作流相似、但形式不同的新一代并行 Agent 工具的对比，信息已于 2026-08-03 在线核实：

工具	Stars	许可证	实际功能
TaskSwarm	尚未发布	MIT	仅发送通知的事件服务；无需一直开着 UI
Claude Squad	8,231	AGPL-3.0	基于 tmux 的并行 Agent 会话终端管理器；其 README 中未发现通知功能
Superset	12,763	Elastic License 2.0（可查看源代码）	围绕并行 Agent 构建的完整代码编辑器；其 README 称“需要关注时会收到通知”
Nimbalyst	1,394	MIT	可视化桌面工作区，配有推送通知的移动端应用；通过托管协作服务进行同步
Paneflow	48	GPL-3.0	原生 Rust 窗格工作区，带有待处理事项队列和桌面通知
Conductor（Melty Labs）	闭源，无公开仓库	专有	仅支持 macOS 的 worktree 仪表板；无法通过 npm 或 PyPI 安装

这些工具都提供了一个可以查看 Agent 工作状态的地方。TaskSwarm 则基于相反的假设构建：你并不会一直盯着看，所以它会主动向你推送通知。与此相邻的是，标准化的 Agent 集成协议 MCP 在同期发展成了独立的主流类别；据 Anthropic 2025 年 12 月的生态系统更新，活跃的公开 MCP 服务超过 10,000 个，SDK 月下载量超过 9,700 万——这反映了同一底层趋势：Agent 正在接入标准化集成点。这也正是 TaskSwarm 自带的包装脚本适配器（taskswarm agent report-status）刻意保持协议无关，而非绑定某个 Agent 的钩子格式的原因。

TaskSwarm 是什么，以及它为何存在

运行一个编码 Agent 就是一场对话。并行运行三四个 Agent 就会变成不断切换标签页的问题：没有任何机制会主动向你推送状态，因此你只能盯着终端反复检查，只为发现其中一个 Agent 已经卡在权限提示上十分钟。TaskSwarm 正是为弥补这一缺口而存在：当会话确实需要人工介入时，向你发送推送通知。

核心部分（事件服务、CLI、实时状态页、Claude Code Hook 集成）采用 MIT 许可证，可免费自托管，适用于个人、团队或任何场景。目前没有推出托管版或付费版。眼下，自托管核心就是完整的产品。

常见问题

它会取代我的看板 / Linear / GitHub Projects 吗？ 不会。那些工具跟踪的是人计划的工作项。TaskSwarm 跟踪 Agent 会话的实时状态，并在状态变化的瞬间通知你。两者用途不同。

我必须使用 Claude Code 吗？ 不必。目前推出的唯一已验证原生集成是 taskswarm hooks install claude-code。Codex、Cursor 或其他工具都可以通过该适配器内部调用的同一基本机制接入：taskswarm agent report-status，可从任何 CLI Agent 的包装脚本中调用。

我的数据会被发送到哪里？ 默认不会发送到任何地方。服务绑定到 127.0.0.1，每个请求都需要 Bearer 令牌，并将状态写入你自己磁盘上的 ~/.taskswarm/（或 TASKSWARM_HOME 指向的位置）。唯一可能离开你设备的可选渠道是 ntfy.sh，除非你明确启用，否则它处于关闭状态。

以后会开始向我收费吗？ 采用 MIT 许可证的核心部分会一直免费。本 README 中介绍的就是产品目前的全部内容，并非试用版，也不是更大产品的受限版本。

为什么不直接用 tmux 并盯着各个窗格？ 这个项目正是为了解决这种现状而诞生的。运行不超过两三个会话时，这种做法还行；但会话更多时，你花在检查窗格上的时间就会超过写代码的时间。

调用命令时，如果服务没有运行，会发生什么？ 需要服务的命令会立即失败并显示明确消息（could not reach TaskSwarm server at http://127.0.0.1:4173 -- is it running? (taskswarm start)），而不是打印堆栈跟踪。没有服务时，task add 和 task list 仍可使用，只是不会补充实时状态信息。

TaskSwarm 究竟是什么？ 它由一个可自托管的事件服务和一个 CLI 组成。Agent 会话，或任何 Agent 的包装脚本，都会向其报告状态（taskswarm agent report-status）；当会话状态变为 blocked、needs-review、failed 或 done 时，它会立即发送本地操作系统通知，并更新实时 SSE 状态页。它不会自行启动、调度或运行 Agent；它只跟踪并推送已在其他地方运行的会话状态。

我可以把 TaskSwarm 当作库使用，而不使用 CLI 吗？ 可以。两个发行版本都提供真正的程序化接口，而不只是一个 bin 入口：npm 上可使用 import { startServer, EventStore } from 'taskswarm-cli'，PyPI 上可使用 from taskswarm import start_server, EventStore。完整导出列表以及每项导出的可运行示例，请参阅上文的 库 API 参考。

平台和安装要求是什么？ npm 版本（taskswarm-cli）需要 Node.js >=18.18.0，对应 package.json 中的 engines 字段。PyPI 版本（同样名为 taskswarm-cli）需要 Python >=3.9，对应 pyproject.toml，其中还声明了 Operating System :: OS Independent。不过，实际使用中有一项平台相关限制：原生操作系统推送通知仅在 macOS 上通过 osascript 触发（参见 src/notify/os-notify.ts）。在 Linux 和 Windows 上，TaskSwarm 会改为输出一行控制台文本并响起终端提示音，而不是发送系统通知；通知仍在本地触发，除非你选择启用 ntfy.sh，否则不会使用它。 TaskSwarm 与 Vibe Kanban 或 paperclip 这样的特定竞品相比如何？ 完整对比请参见上方的对比表，简而言之：paperclip 和 Multica 旨在像组织架构图一样运行并展示一整支 Agent 团队；而 Vibe Kanban 曾是一个完整的规划与评审工作区，但其背后的公司已经关闭（截至本文撰写时，其 README 中有一则关闭公告）。这三者的 README 中都没有提到推送／桌面通知功能。TaskSwarm 完全跳过看板，只专注于一件事：在会话需要你时立即推送提醒。

我可以在商业产品或付费产品中使用 TaskSwarm 吗？ 可以。核心部分（事件服务、CLI、实时状态页、Claude Code 钩子集成）采用 MIT 许可，不限制使用领域，因此可以将其自托管在商业产品、付费服务或内部工具中。与上方对比表中的 Multica 相比，这是一项实实在在的优势；Multica 使用经过修改的 Apache-2.0 许可，该许可明确限制了托管式商业用途。

贡献

欢迎提交问题和拉取请求。提交 PR 前：

npm run lint
npm run typecheck
npm run test:coverage

三项检查都必须通过。对于 Python 发行版，请运行 cd python && pip install -e ".[dev]" && pytest。完整检查清单（涵盖两个代码库）请参见 CONTRIBUTING.md。

许可证

MIT。请参见 LICENSE。个人或团队均可免费自托管、修改和再分发。此版本不提供托管版或付费版。