用途
当多个人或多个 Claude 会话在同一个代码仓库中工作时，没有人知道其他会话在做什么。Claude Code 自带的 ListAgents / SendMessage 只能触达同一台机器或同一账号下的会话，也无法阻止一次会撞车的提交。claude-session-relay 通过一个插件（团队场景再加一个自托管中继）让每个会话：
- 出现在共享看板上：谁在哪里工作、在哪个分支和 ticket 上、正在改哪些文件（从分支和当前工作自动声明）；
- 可以给其他会话发消息：备注、提问和回答，几秒内送达；
- 在发生冲突的 git 操作前被拦下：当别人在同一分支上时阻止 git push，当别人在改同样文件时阻止 git commit。
主要能力
- 共享看板：显示各会话的位置、分支、ticket 和正在改动的文件。
- 会话间消息：支持发送备注、提问与回答，由后台长轮询在数秒内送达。
- git 冲突检查：在 commit / push 前检查是否与他人冲突并拦截。
- 本地模式：单人使用无需任何配置，会话通过 ~/.claude/session-relay/ 下的文件共享看板、消息和 git 检查，无服务器、无 token、无账号，数据不出本机。
- 团队中继：一个中继可承载多个相互隔离的团队，按文件夹决定会话加入哪个团队，或设为私有（只有自己的会话可见）。未映射的文件夹完全不上中继。
- 中继根 URL 提供浏览器看板页面，输入 token 即可查看。
- MCP 连接器：供不使用本地 Claude Code 的人（claude.ai、桌面和移动应用、Cowork）以远程 MCP 连接器方式接入，获得同样的看板、消息和冲突检查，以及同样的团队隔离。
使用方式
本地单人：安装插件并重启 Claude Code 即可自动以本地模式运行，每个会话启动时会显示会话名和本机看板。可选的显式配置可指定参与的文件夹和人员名称。
团队：三步——运行一个中继、安装插件、使用。中继建议置于 HTTPS 之后（文档给出 Caddy 配置示例）。中继管理命令包括 relay person:create、person:revoke、team:list、team:rename、team:remove、cleanup 等。客户端需要在 Claude Code 中告知中继地址以及哪些文件夹属于哪个团队（/session-relay:session setup 会引导完成）。文件夹匹配以最长匹配为准，未映射的文件夹不接入。可添加多个中继，例如每个组织一个。
日常操作大多由 hooks 自动完成：会话启动时注册、发送心跳（同时更新分支与声明）、在 git commit / push 前检查、在工具调用后和每次提示时投递新消息。listen 在每个会话中后台运行并保持长轮询。命令 /session-relay:session 提供 status、start（声明正在做什么）和 done（收尾并告知他人）。
云端使用：在 claude.ai、桌面、Cowork 的 Settings > Connectors > Add custom connector 中填入 https://relay.example.com/mcp，Claude 会打开中继的授权页，粘贴 person:create 得到的 relay token 并点击 Approve；通过 OAuth（动态客户端注册、PKCE）连接，relay token 不会交给 Claude。此方式需要 config.php 中的 public_url（或 .env 中的 RELAY_PUBLIC_URL），且 Web 服务器需把所有路径（包括 /.well-known/oauth-protected-resource、/.well-known/oauth-authorization-server、/oauth/* 和 /mcp）交给 public/index.php，并传递 Authorization 头。另有仅需 PHP 8.4+ 的 stdio bridge，供启动本地进程的客户端使用。MCP 工具包括 whoami、board、register、unregister、check、send、ask、answer 和 inbox。
适用场景
- 同一人在一台机器上并行运行多个 Claude Code 会话，希望彼此协调、避免 git 撞车。
- 多人（或多个会话）在同一仓库协作，需要看清彼此的工作位置并互相留言。
- 团队希望按文件夹划分隔离的团队，并让不安装本地 Claude Code 的成员通过 claude.ai / Cowork 接入同一看板。
限制
- Claude Code 的 ListAgents / SendMessage 本身无法跨机器或跨账号，也没有冲突拦截，这正是本工具要补足的部分。
- 云端（MCP）方式没有 hooks：不会自动注册、发送心跳、在提交或推送前检查、自动投递消息，需要 Claude 主动调用 register、inbox 和 check。
- 中继不可用时不阻塞工作：只会给出警告并继续。
- 缺少 public_url 时，/mcp、/oauth/* 和 OAuth 的 /.well-known 文档返回 503，其余部分仍可用。
- 已知残留问题：消息 id 是全局且顺序的，响应时间未做填充处理。
- 团队隔离在服务端以一条 SQL 规则对所有端点强制执行，无权查看的对象表现如同不存在。
- 团队中继需要 Docker，或 PHP 8.4+ 加 pdo_pgsql 与 PostgreSQL；本地模式不需要服务器。
- 客户端环境要求：支持插件的 Claude Code；Windows 需 Windows PowerShell 5.1（内置）和 Git Bash，macOS/Linux 需 PowerShell 7（pwsh）和 bash；git 2.31 或更新。
- 消息只传输元数据（会话名、仓库与分支名、文件路径、短信文本），不传输代码。Token 为 32 随机字节，仅以 SHA-256 哈希存储。
- 其他会话发来的消息以数据形式呈现给 Claude，永不作为指令；会话只自行回答事实性问题，涉及决策的内容转交自己的用户。
- 采用 MIT 许可证。
