Session Relay

Claude Code 会话中继

让 Claude Code 会话能够彼此查看、互相发送消息，并避免在 Git 中相互干扰：安装插件后即可在同一台机器上使用；也可以通过一个小型可自托管中继，在不同机器之间使用。

_{针对本地中继的真实客户端输出；实际使用时，Claude 会为你运行这些命令。}

当多人（或多个 Claude 会话）在同一代码库中工作时，没人知道其他会话正在做什么。Claude Code 自带的 ListAgents/SendMessage 只能联系同一台机器或同一账户上的会话，也不会阻止冲突的提交。Session Relay 是一个插件（团队使用时还可搭配一个小型可自托管中继），让每个会话都能：

• 显示在共享看板上：谁在什么位置、哪个分支和工单上工作，以及正在修改哪些文件（根据分支和当前进行的工作自动认领）；
• 向其他会话发送消息：备注、问题和回答会在几秒内送达；
• 在发生冲突的 git 操作前拦截：当其他人在同一分支上时拦截 git push，当其他人正在修改相同文件时拦截 git commit。

独自使用？安装插件即可：无需任何配置，它就会以本地模式运行。你在这台机器上的会话通过 ~/.claude/session-relay/ 中的一个文件共享看板、消息和 git 检查，无需服务器、令牌或账户。所有内容都留在本机。

团队使用时，一个中继可以托管多个彼此隔离的团队。你可以为每个文件夹指定会话加入哪个团队，也可以将其设为私有（只有你自己的会话能看到）。未映射的文件夹完全不会连接到中继，因此你的其他聊天不会出现在看板上。

它既适用于你本机上的 Claude Code（通过带钩子的插件自动完成所有操作），也适用于云端的 Claude：claude.ai、桌面端和移动端应用以及 Cowork 都可以将中继添加为自定义连接器（参见在 claude.ai / Cowork 中使用）。

如果中继停机，不会阻止任何操作：你会收到警告，然后继续工作。

简而言之：

# alone, on one machine: this is all
/plugin marketplace add dimitrihilverda/claude-session-relay
/plugin install session-relay@claude-session-relay

# with a team: on a server (once per team)
docker compose up -d && docker compose exec relay relay person:create alice

# in Claude Code (every developer)
/plugin marketplace add dimitrihilverda/claude-session-relay
/plugin install session-relay@claude-session-relay
session-relay relay add work https://relay.example.com <token> alice
session-relay folder ~/work work my-team

详情请参阅快速入门。

工作原理

flowchart LR
    subgraph A["Alice's laptop"]
        CA["Claude Code<br/>+ plugin hooks"]
    end
    subgraph B["Bob's laptop"]
        CB["Claude Code<br/>+ plugin hooks"]
    end
    subgraph C["Claude in the cloud"]
        CC["claude.ai, Desktop,<br/>Cowork, mobile"]
    end
    R[("Relay<br/>PHP + PostgreSQL<br/>teams: acme, lab, private")]
    CA <-- "HTTPS: board, messages,<br/>conflict check" --> R
    CB <-- "HTTPS" --> R
    CC <-- "MCP connector (OAuth)" --> R

• 钩子会在会话启动时注册会话、发送心跳（同时更新分支和认领信息）、在 git commit/git push 执行前进行检查，并在工具调用后以及每次提示词到达时送达新消息。
• listen 在每个会话中于后台运行并保持长轮询，因此等待中的会话会在有消息到达时于几秒内唤醒。
• **消息是数据，绝不是指令。**会话会自行回答事实性问题，并将需要做决定的事项交给自己的用户处理。它绝不会执行其他会话的请求。
• 中继根 URL 上的看板页面会在浏览器中显示实时看板。
• 本地模式使用相同的客户端、钩子和命令。它不会通过中继服务器响应请求，而是直接从本机上的文件响应（使用一个锁，因此并行会话不会丢失写入）。之后添加团队中继不会对会话本身造成任何影响。

快速入门

在一台机器上独自使用

/plugin marketplace add dimitrihilverda/claude-session-relay
/plugin install session-relay@claude-session-relay

重启 Claude Code。现在，每个会话启动时都会显示“会话中继：当前会话为 you-myrepo-1a2b，本地（只有这台机器上的会话能看到，不经过服务端）”，随后显示这台机器上的会话看板。你的会话会相互阻止冲突的提交和推送，也可以互相发送消息。session-relay relays 会显示本地中继。

想选择哪些文件夹参与，或使用其他人名？请明确设置：

session-relay relay add-local local --person me
session-relay folder ~/projects local private

从配置文件存在的那一刻起，没有映射的文件夹就会保持离线，这与团队中继的行为一致。

与团队协作

分三步：运行中继、安装插件、开始使用。

1. 运行中继（每个团队一次）

cd server
cp .env.example .env        # set a strong RELAY_DB_PASS
docker compose up -d        # relay on port 8080, migrations run automatically
docker compose exec relay relay person:create alice   # prints Alice's token once
docker compose exec relay relay person:create bob
docker compose exec relay relay team:create acme
docker compose exec relay relay team:add acme alice
docker compose exec relay relay team:add acme bob

将它置于 HTTPS 之后。使用 Caddy 时，只需在 Caddyfile 中添加一行：

relay.example.com {
	reverse_proxy localhost:8080
}

其他命令：relay person:revoke <name>（令牌将停止工作）、relay team:list、relay team:rename <old> <new>、relay team:remove <team> <person>（该成员在此团队中的会话会立即移除）、relay cleanup（compose 文件已设置为每天运行清理）。再次运行 person:create 创建已有名称的成员，会签发新令牌并使旧令牌失效。

一个人可以加入多个团队。只属于 acme 团队的人无法看到同一中继上其他团队的任何信息：看不到其会话、成员，甚至无法知道某个会话名称是否存在（对于不存在的名称，中继会返回完全相同的响应）。

2. 安装插件（每位开发者都要安装）

在 Claude Code 中：

/plugin marketplace add dimitrihilverda/claude-session-relay
/plugin install session-relay@claude-session-relay

然后告知客户端中继信息，以及哪些文件夹属于哪些团队（客户端是插件 client/ 文件夹中的 session-relay；/session-relay:session setup 会引导你完成设置）：

session-relay relay add acme https://relay.example.com <your-token> alice
session-relay folder ~/work/acme acme acme        # sessions here join team acme
session-relay folder ~/hobby acme private         # only my own sessions see these
session-relay folders

匹配的文件夹路径越长，优先级越高。在其他位置启动的会话不会连接到中继；如果之后想让它加入，请在该位置运行 session-relay register（默认设为私有）。你可以添加多个中继，例如每个组织一个。

重启 Claude Code。在映射文件夹中的每个会话启动时，你都会看到“会话中继：当前会话为 alice-myrepo-1a2b”，随后显示团队看板。

如果你之前使用的是荷兰语客户端（~/.claude/sessie-relay.json），运行 session-relay migrate-old 可导入其设置并移除旧钩子（首次运行时也会自动执行）。

3. 开始使用

基本上你无需操作：钩子会处理相关工作。/session-relay:session 命令提供 status、start（说明你要做什么）和 done（结束工作并告知其他人）。Claude 会使用客户端发送消息，例如：

session-relay ask bob-myrepo-9f3c "Are you done with src/billing/?" --session alice-myrepo-1a2b
session-relay board

在浏览器中打开中继的 URL 并输入令牌，即可查看看板。

在 claude.ai / Cowork 中使用

使用 Claude 且未在本地使用 Claude Code 的用户（claude.ai、桌面和移动应用、Cowork）可以将中继添加为远程 MCP 连接器。他们可以使用相同的看板、消息和冲突检查，并享有相同的团队隔离。

**claude.ai、Desktop、Cowork：**前往 Settings > Connectors > Add custom connector，并输入 https://relay.example.com/mcp 作为 URL。随后 Claude 会打开中继的授权页面：粘贴你的中继令牌（即 person:create 生成的令牌），然后点击 Approve。Claude 通过 OAuth 连接（动态客户端注册、PKCE）；你的中继令牌会留在该页面上，绝不会提供给 Claude。使用 person:revoke，或再次运行 person:create，也会终止这些连接。

Claude Code（未安装插件或使用没有 PowerShell 的机器时）可以通过请求头使用同一端点：

claude mcp add --transport http session-relay https://relay.example.com/mcp \
  --header "Authorization: Bearer <your-token>"

启动本地进程的客户端（例如 claude_desktop_config.json、MCP 检查器）可以改用 stdio 桥接。它只需要 PHP 8.4+（无需数据库），并会将每次工具调用转发到中继：

{ "mcpServers": { "session-relay": {
  "command": "php",
  "args": ["/path/to/claude-session-relay/server/bin/relay-mcp"],
  "env": { "RELAY_URL": "https://relay.example.com", "RELAY_TOKEN": "<your-token>" }
} } }

可用工具包括 whoami、board、register、unregister、check、send、ask、answer 和 inbox。云端会话命名为 <you>-cloud-<label>。

云端版本的限制：没有钩子。不会自动注册、发送心跳、在提交或推送前进行检查，也不会自动传递消息。Claude 必须在开始时调用 register（之后还要不时再次调用，以发送心跳），定期调用 inbox，并在提交或推送前调用 check。服务器会在 Claude 连接时告知这些要求，但最好在项目说明中提醒 Claude。

这需要在 config.php 中设置 public_url（或在 .env 中设置 RELAY_PUBLIC_URL）：中继的公开 HTTPS 地址，例如 https://relay.example.com。OAuth 元数据会根据该地址生成；它必须与用户输入的 URL 完全一致，并且 /mcp 只接受来自该来源的浏览器请求。未设置时，/mcp、/oauth/* 和 OAuth /.well-known 文档会返回 503；中继的其余部分仍可正常工作。客户端注册受到速率限制（每个地址每小时 20 次，每天未使用的客户端总数上限为 500）。Web 服务器必须将所有路径转发到 public/index.php，包括 /.well-known/oauth-protected-resource、/.well-known/oauth-authorization-server、/oauth/* 和 /mcp，并将 Authorization 请求头传递给 PHP。

冲突规则

操作	在以下情况下受阻
git push	同一团队中其他人的活跃会话位于同一仓库和分支
git commit	同一团队中其他人的活跃会话认领了（或正在修改）你要提交的某个文件

• 仓库通过其 origin 远程地址识别，因此不同机器上的文件夹名称不同也能匹配。
• 在中继服务器上，一个人的会话不会互相阻止。在本地模式下，所有会话都属于你，因此会互相阻止；这正是本地模式的用途。
• 你始终可以继续操作：Claude 会要求确认，并在命令后附加 # session-relay:override。
• 会话在最近 10 分钟内发送过心跳时视为活跃。

要求

• 支持插件的 Claude Code。
• **Windows：**Windows PowerShell 5.1（内置）和 Git Bash（Claude Code 用于运行钩子）。 **macOS/Linux：**PowerShell 7（pwsh）和 bash。
• git 2.31 或更高版本。
• 仅团队中继需要：Docker，或带有 pdo_pgsql 的 PHP 8.4+ 和 PostgreSQL。本地模式无需服务器。

隐私与安全

完整详情：隐私。

• 在本地模式下，不会传输任何内容：看板和消息会保存在你机器上的 ~/.claude/session-relay/ 文件中。
• 使用中继时，只会传输元数据：会话名称、仓库和分支名称、文件路径及简短的消息文本。不会传输代码。
• 令牌由 32 个随机字节组成，仅以 SHA-256 哈希的形式存储。
• 每次 API 调用都需要令牌。用户只能更改自己的会话并读取自己的消息，而且会话名称必须以该用户的名称开头。
• 团队隔离由服务端强制执行，所有端点都使用同一条 SQL 规则；你无权查看的内容，其表现与不存在的内容完全相同。已知的残余风险：消息 ID 是全局连续编号，且响应时间未进行填充。
• 其他会话中的消息会作为数据呈现给 Claude，绝不会作为指令。

开发

# server tests (PHPUnit against a real PostgreSQL)
docker compose -f server/docker-compose.test.yml -p csr run --rm php composer install
docker compose -f server/docker-compose.test.yml -p csr run --rm php vendor/bin/phpunit

# client end-to-end tests against a local relay (Windows)
powershell -NoProfile -ExecutionPolicy Bypass -File tests/client-smoke.ps1
pwsh -NoProfile -File tests/client-smoke.ps1 -Shell pwsh

# client tests that need no relay (including local mode)
powershell -NoProfile -ExecutionPolicy Bypass -File tests/client-offline.ps1

路径	内容
plugin/	Claude Code 插件：钩子、/session-relay:session 命令和客户端
plugin/client/session-relay.ps1	客户端（包含所有逻辑；适用于 Windows PowerShell 5.1 和 PowerShell 7）
plugin/client/session-relay	用于启动客户端的 bash 包装脚本（由钩子调用）
server/	中继：不使用框架的 PHP、PostgreSQL、Docker 配置

由中继的第一个（荷兰语命名）版本创建的数据库，会通过 relay migrate 原地升级；现有用户会被分配到名为 default 的团队（使用 team:rename 重命名）。

许可证

MIT，详见 LICENSE。