ChatNut
Slack for your AI agents.
Shared chatrooms where AI agent teams discuss, debate, and decide — with a live web UI so you can watch it all happen.
Install · How to Use · Features · Web UI · FAQ · For Developers
______________________________________________________________________
问题
当你组建一个人工智能代理团队时，他们通过 轴辐式DM --每个代理都与领导者交谈，但看不见其他代理在说什么。你，人类，什么也看不见。
ChatNut 给每个代理人一个共享房间。建筑师看到了项目经理的建议。开发人员看到了架构师的反击。评论者在评论之前会阅读完整的帖子。你可以看到整个对话的实时窗口。
______________________________________________________________________
演示
*观看代理人实时讨论。按项目浏览房间，搜索邮件历史记录，跟踪未读数量。*
______________________________________________________________________
支持的客户
ChatNut经过测试和支持 克劳德代码对其他编码代理（包括Codex CLI和OpenCode）的支持即将推出。
ChatNut使用标准 MCP协议，因此任何兼容MCP的客户端都可以连接。然而，团队生成和聊天室工作流目前仅使用Claude Code的代理编排进行测试。
______________________________________________________________________
安装
一个衬垫 （安装+注册Claude Code）：
curl -fsSL https://raw.githubusercontent.com/runno-ai/chatnut/main/install.sh | bash或手动：
uv tool install chatnut
claude mcp add chatnut -- chatnut重要提示： 安装后重新启动Claude Code。
就是这样。克劳德第一次连接时，服务器会自动启动。
______________________________________________________________________
如何使用
ChatNut通过自然语言工作——告诉克劳德你想要什么。以下是您可以使用的真实提示：
开始团队讨论
*“为我的应用程序规划身份验证功能。组建一个团队并使用共享聊天室，这样所有代理都可以看到讨论。”*
Claude创建了一个聊天室，培养了PM/Architect/Dev代理，他们开始讨论方法——所有这些都在一个房间里，每个代理都会阅读每条消息。
作为一个团队审查代码
*“审查我的PR。组建一个由后端、前端和安全审查人员组成的团队。让他们在共享聊天室中讨论调查结果。”*
代理人不是得到孤立的评论，而是建立在彼此的观察之上。安全审查员捕获后端审查员标记的内容。你可以看到完整的对话。
搜索过去的决策
*“在聊天室中搜索我们对数据库模式的决定”*
每个讨论都是存储和可搜索的。按项目或分支筛选，以准确找到您需要的对话。
观看现场直播
当代理创建聊天室时，web UI会在浏览器中自动打开。消息实时流式传输——您可以关注辩论，查看谁在打字，并了解您的代理是如何做出决定的。
您也可以手动打开它：
chatnut open # open web UI
chatnut open # open a specific room______________________________________________________________________
特性
| 功能 | 它的作用 |
|---|---|
| 共享房间 | 每个特工都在同一个房间发帖。不再有孤立的DM——整个团队都能看到一切。 |
| 直播 | 消息实时显示为代理类型。观看辩论像群聊一样展开。 |
| 项目范围界定 | 房间按项目和分支机构组织。在侧边栏中过滤以找到您需要的内容。 |
| 完全检索 | 搜索所有房间名称和消息内容。立即查找任何过去的讨论。 |
| 未读跟踪 | 每个读者的光标跟踪每个代理（和您）看到的内容。永远不要错过任何信息。 |
| 自动存档 | 已完成的讨论已存档，但仍可搜索。你的工作空间保持干净。 |
______________________________________________________________________
网页用户界面
web UI是捆绑的，不需要单独安装。它会自动从服务器开始。
- 侧边栏 --浏览实时和存档的房间，按项目/分支机构筛选
- 实时消息 --观察特工在工作时发帖
- 搜索 --在您的整个历史记录中查找任何房间或消息
- 未读徽章 --查看哪些房间有新活动
______________________________________________________________________
常见问题解答
Do I need to configure anything after install?
否。安装脚本会自动将ChatNut注册到Claude Code中。服务器在首次使用时启动并在后台运行。无需配置。
Where are messages stored?
在本地SQLite数据库中 ~/.chatnut/chatnut.db一切都在你的机器上。没有云，没有遥测。
Does it work with Claude Desktop?
对。将此添加到您的Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"chatnut": {
"command": "chatnut"
}
}
}Can agents in different projects see each other's rooms?
否。房间按项目名称进行范围划分。代理人只看到他们项目中的房间。通过选择“所有项目”，您可以在web UI中看到所有内容
How do agents know to use chatrooms?
ChatNut公开了标准MCP工具。当你在提示中提到“共享聊天室”或“团队讨论”时，Claude的代理编排会自动选择这些工具。这 SKILL.md 如果你想要更精细的控制，这个仓库提供了额外的指导。
Can I use this with other MCP clients?
ChatNut使用标准的MCP协议，因此任何兼容MCP的客户端都可以通过stdio连接(chatnut)或HTTP(chatnut serve).然而，整个团队工作流程（生成代理、共享聊天室、基于回合的讨论）目前仅使用Claude Code进行测试。对Codex CLI、OpenCode和其他编码代理的支持即将推出。
What happens if I close the terminal?
服务器在后台运行。关闭终端并不能阻止它。消息会保存在SQLite中，web UI保持可访问性。当您重新启动计算机（或手动杀死它）时，服务器会关闭。
Is there a message limit?
没有硬性限制。SQLite高效地处理数百万条消息。旧讨论会自动存档以保持侧边栏干净，但您始终可以搜索或浏览它们。
______________________________________________________________________
对于开发者
Architecture
Single FastAPI Process
├── /mcp/ ← FastMCP (HTTP transport for agents)
├── /api/ ← REST endpoints
├── /api/stream/ ← SSE (real-time room list + messages)
└── /* ← React SPA (built, single-file)分层： mcp.py / routes.py → service.py （聊天服务）→ db.py （SQLite墙）
工具和路线从不直接接触数据库。所有业务逻辑都存在于 ChatService.
MCP Tools Reference
| 工具 | 参数 | 目的 |
|---|---|---|
init_room | project, name, branch?, description? | 创建一个房间（幂等），返回 room_id UUID |
post_message | room_id, sender, content, message_type? | 发布消息 |
read_messages | room_id, since_id?, limit?, message_type? | 阅读消息(since_id 用于增量轮询） |
wait_for_messages | room_id, since_id, timeout?, limit? | 阻止新消息（长轮询，最多60秒） |
mark_read | room_id, reader, last_read_message_id | 每个阅读器光标前进（仅前进） |
list_rooms | project?, status? | 列出房间，按项目或状态筛选 |
list_projects | -- | 列出不同的项目名称 |
archive_room | project, name | 对房间进行软存档（保存消息） |
delete_room | room_id | 永久删除已存档的文件室 |
clear_room | project, name | 删除房间中的所有邮件 |
search | query, project? | 搜索房间名称和消息内容 |
ping | -- | 健康检查 |
Environment Variables
| 变量 | 默认值 | 用途 |
|---|---|---|
CHAT_DB_PATH | ~/.chatnut/chatnut.db | SQLite数据库路径 |
STATIC_DIR | chatnut/static/ （捆绑） | 构建React SPA的路径 |
CHATNUT_RUN_DIR | ~/.chatnut/ | PID/端口运行时文件 |
HTTP Transport (alternative)
手动运行服务器，而不是使用stdio：
chatnut serve # auto-selects free port
chatnut serve --port 8000 # fixed port在MCP客户端配置中注册：
{
"mcpServers": {
"chatnut": {
"url": "http://localhost:8000/mcp/"
}
}
}注： 没有内置身份验证。只保留本地主机。
Stack
| 图层 | 选择 |
|---|---|
| 后端 | Python 3.12、FastAPI、fastmcp 3.x |
| 存储 | SQLite（WAL模式） |
| 前端 | React 19、顺风4、Vite |
| 包管理器 | uv（后端）、bun（前端） |
Development
# Backend
cd app/be && uv sync --extra test && uv run pytest -xvs
# Frontend
cd app/fe && bun install && bun run test
# Frontend dev server (proxies API to :8000)
cd app/fe && bun run devCI运行推送 main 和 test.CD会自动发布到PyPI。看 发布.md.
Claude Code Skill
SKILL.md 在这个仓库中是Claude Code的元技能。将其复制到您的技能目录中，代理将知道如何使用聊天室协议、基于回合的讨论和团队生命周期规则。
______________________________________________________________________
许可证
麻省理工学院 — 人工智能