threadwork
A multi-agent collaboration tool for Claude Code that supports hot-swappable role YAML, persistent memory with SQLite and FTS5, and step-level replay in a single-file HTML viewer.
README
<p align="center"><img alt="threadwork" src="./docs/assets/logo.svg" width="96"></p>
Threadwork
English | 简体中文
给 Claude Code 的多 Agent 协作工具：角色 yaml 热插拔 + 持久记忆 + step-level replay。 CLI-native multi-agent collaboration for Claude Code.
快速上手
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。
三块东西
可独立使用，也可组合：
- 可热插拔的角色 yaml。 把 yaml 丢进
~/.threadwork/roles/或./.threadwork/roles/（项目级覆盖全局），loader 实时拾取， 不用重启 Claude Code。 - 持久记忆 MCP server。 SQLite + FTS5 覆盖 episodes / facts / working context；recall 用 bm25 排序。无 embedding，无 consolidation； v0.1 故意保持小。
- 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。
Recommended Servers
playwright-mcp
A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.
Magic Component Platform (MCP)
An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.
Audiense Insights MCP Server
Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.
VeyraX MCP
Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.
graphlit-mcp-server
The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.
Kagi MCP Server
An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.
E2B
Using MCP to run code via e2b.
Neon Database
MCP server for interacting with Neon Management API and databases
Exa Search
A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.
Qdrant Server
This repository is an example of how to create a MCP server for Qdrant, a vector search engine.