agora-mcp

---

已停止维护

Claude Code 现在可以自行完成这些事。 会话可以彼此协调、查看对方的工作并共享状态，无需额外的 MCP 服务，而这正是本项目原本要提供的功能。

此仓库已归档并设为只读。它仍然可用——npm 上的内容没有删除，最后发布的版本仍可安装——但本项目不会再维护，也没有维护的必要。 如果你想了解这个构想而非使用这个包，完整设计都在 docs/ 中，许可证允许你使用它。

为什么

当多个 Claude Code 会话同时（或只是在一天之内）处理同一个仓库时，它们之间互不知情。没有任何会话知道其他会话改动了什么，它们会悄无声息地覆盖相同文件，而且关闭会话后上下文也会丢失。

agora 为每个会话提供一个共享空间，供其记录工作进展并查看其他会话的工作。

工作原理

整个系统就是每个仓库一个 SQLite 文件：<repo-root>/.agora/space.db（采用 WAL 模式，因此多个进程可以同时读写而不会损坏数据）。

• 无需任何人运行服务端。 没有守护进程，也没有 Web 应用。“空间”就是这个文件。
• 仓库中的每个会话都会写入自己的操作，并读取其他会话的操作。
• 因为它是一个文件，所以会自动持久保存——关闭所有内容，明天再回来，状态依然保留。
• 它是一个共享看板，不是实时聊天：会话会在启动时、即将编辑时（冲突），或主动查询时（使用工具）获取信息。

适用于多工作树：.db 位于主仓库根目录，因此仓库的所有会话（包括位于不同工作树中的会话）都共享同一个 agora。

功能

• 🟢 查看当前有哪些会话以及每个会话正在操作哪些文件，实时掌握动态。
• ⚠️ 冲突警告——在编辑某个文件或操作某个分支之前，提醒你另一个活跃会话已占用它。
• 📋 项目恢复——打开会话即可获取其他会话所做工作的摘要。
• 📓 活动日志——按仓库记录所有事件的时间线。
• ✉️ 会话之间的备注（定向发送或广播）。
• 🛡️ 尽力而为的钩子——无论发生什么都会以 0 退出，绝不会阻塞会话。

要求

• Bun 1.3+
• git 2.x
• Claude Code（或任何 MCP 客户端）

安装

通过 npm——无需克隆：

# Register the MCP server — nothing to install for this part
claude mcp add agora -- bunx --bun @vorluno/agora-mcp

# The hooks need the CLI on your PATH. Install once, then run it from any repo.
# Idempotent; add --project to scope it to the current repo only.
bun add -g @vorluno/agora-mcp
agora-init init

从源代码安装——如果你想修改它：

git clone https://github.com/vorluno/agora-mcp.git
cd agora-mcp
bun install
bun run src/cli.ts init
claude mcp add agora -- bun run /absolute/path/to/agora-mcp/src/index.ts

配置

任何 MCP 客户端都可使用。mcpServers 配置项：

{
  "mcpServers": {
    "agora": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/agora-mcp/src/index.ts"]
    }
  }
}

对于 Claude Code，claude mcp add（见上文）会为你写入此配置。对于 Warp 或 Cursor，将此代码片段粘贴到它们的 MCP 设置中。

工具

工具	说明
resume_project	agora 摘要：活跃会话、近期活动、冲突和未读备注。
who_is_here	活跃会话，以及每个会话正在操作的文件。
activity_log	仓库事件日志，可按时间或会话筛选。
check_collision	是否有其他活跃会话正在操作这些文件或此分支？
leave_note	给另一个会话留言（或向所有会话广播）。
read_notes	阅读发送给某个会话的备注（并将其标记为已读）。

如何检测冲突

• 文件冲突： 2 个或更多不同会话对同一文件持有有效的 writing 声明。
• 分支冲突： 2 个或更多活动会话位于同一分支，但处于不同的工作树中。

只统计仍在运行的会话，因此，未正常退出的会话不会导致误报。

自动捕获（钩子）

init 会安装 5 个尽力而为的钩子（它们始终 exit 0）：

钩子	功能
SessionStart	注册会话，并将 agora 摘要注入上下文（也会在 /resume 和上下文压缩后触发）。
PostToolUse (Edit/Write)	记录文件声明和事件；出现新冲突时发出警告。
PreToolUse (Edit/Write)	如果其他会话已持有该文件，会在你编辑之前发出警告。
Stop / SessionEnd	将会话标记为空闲 / 已停止，并释放其声明。

开发

bun test          # full suite (incl. a real WAL concurrency test)
bunx tsc --noEmit # type-check

采用测试优先的方式，分 14 项 TDD 任务构建，并对每项任务和整个分支进行审查。

贡献与安全

请先阅读 CONTRIBUTING.md——其第一行会告诉你拉取请求是否会被考虑。漏洞请发送至 [email protected]，切勿在 issue 中报告：请参阅 SECURITY.md，其中承诺的唯一响应时间是 72 小时内确认收到报告。

许可证

Apache-2.0 © 2026 Vorluno。请参阅 NOTICE。

截至 0.1.0（含）采用 MIT 许可证。这些版本仍受 MIT 许可证保护——已授予的许可证不能撤销。从 0.2.0 起采用 Apache-2.0，明确授予专利权。

---