Threadwork

English | 简体中文

给 Claude Code 的多 Agent 协作工具：角色 yaml 热插拔 + 持久记忆 + step-level replay。 CLI-native multi-agent collaboration for Claude Code.

CI License: MIT npm version Node

快速上手

npm install -g threadwork-cli
threadwork init                # 自动注册 MCP 到 ~/.claude.json（带备份 + 原子重命名）
threadwork roles list          # 看一眼默认的四个角色

然后在 Claude Code 里直接调用 threadwork 技能；任务跑完后用 threadwork replay <task_id> 看 step-level 时间线（--serve 直接打开浏览器）。

Demo

asciinema 脚本在 bench/demo.cast。本地用 node bench/build-gif.mjs 渲染成 GIF（需要 PATH 上有 agg），渲染产物 bench/demo.gif 已 commit，CI 卡死 ≤2 MB。

为什么不用 X

需求	ruflo	deer-flow	Threadwork
不 fork 就能自定义角色	否 — 16 个角色硬编码	部分 — 改代码	是 — 一个 yaml 一个角色
不重启就能改角色	否	否	是 — chokidar 监听，<500 ms
原生跑在 Claude Code 里	否 — 独立 Python server	否 — 独立 Python server	是 — npm + MCP，无独立守护
任务级 replay	否	否	是 — 单文件静态 HTML viewer
跨 session 持久记忆	否	部分 — 向量库	是 — SQLite + FTS5，内容哈希去重
没有 vendor 锁	是	是	是

定位：ruflo 但角色不硬编码；deer-flow 但带个 debugger。

三块东西

可独立使用，也可组合：

1. 可热插拔的角色 yaml。 把 yaml 丢进 ~/.threadwork/roles/ 或 ./.threadwork/roles/（项目级覆盖全局），loader 实时拾取， 不用重启 Claude Code。
2. 持久记忆 MCP server。 SQLite + FTS5 覆盖 episodes / facts / working context；recall 用 bm25 排序。无 embedding，无 consolidation； v0.1 故意保持小。
3. Step-level trace replay。 每个 memory 调用都自动记 trace。 threadwork replay <task_id> 渲染单文件 HTML，分角色 swim-lane + 点击查看详情面板。无前端框架，无服务端。

状态

预发布，闭源 alpha 阶段。详见 docs/internal/alpha-beta.md（闭源 beta 计划与反馈渠道）。MIT 许可证。

文档

• docs/install.md — 安装、MCP 注册、卸载
• docs/first-run.md — 60 秒跑通第一个 orchestration
• docs/custom-role.md — 怎么写并分享一个 role yaml
• docs/troubleshooting.md — 跑挂了去看哪儿
• CONTRIBUTING.md — 贡献指南（alpha 阶段先收 issue）
• SECURITY.md — 安全报告流程
• CHANGELOG.md — 版本变更记录

License

MIT — 见 LICENSE。