# Session Relay for Claude Code
[](LICENSE)
[](https://github.com/dimitrihilverda/claude-session-relay/releases)
[](#2-install-the-plugin-every-developer)
[](#use-from-claudeai--cowork)
Let Claude Code sessions see each other, message each other and stay out of each other's way in
git: on **one machine** right after installing the plugin, or across **different machines** with a
small self-hosted relay.
Real client output against a local relay; in practice Claude runs these commands for you.
When several people (or several Claude sessions) work in the same repositories, nobody knows
what the other sessions are doing. Claude Code's own `ListAgents`/`SendMessage` only reach
sessions on the same machine or the same account, and never stop a colliding commit. Session
Relay is a plugin (plus, for teams, a tiny self-hosted relay), so that every session:
- **appears on a shared board**: who is working where, on which branch and ticket, and which
files it is changing (claimed automatically from the branch and the open work);
- **can message other sessions**: notes, questions and answers, delivered within seconds;
- **is stopped before a colliding git action**: a `git push` when someone else is on that
branch, a `git commit` when someone else is changing the same files.
**Alone?** Install the plugin and you are done: without any configuration it runs in **local
mode**. Your sessions on this machine share a board, messages and the git check through a file in
`~/.claude/session-relay/`, with no server, no token and no account. Nothing leaves the machine.
**With a team,** one relay can host several **isolated teams**, and you decide per folder which team a session
joins, or that it is **private** (only your own sessions see it). Folders you don't map stay off
the relay entirely, so your other chats never show up on a board.
It works from Claude Code on your own machine (a plugin with hooks, so everything happens
automatically) and from Claude in the cloud: claude.ai, the desktop and mobile apps and Cowork
add the relay as a custom connector (see [Use from claude.ai / Cowork](#use-from-claudeai--cowork)).
If the relay is down, nothing is blocked: you get a warning and carry on.
**In short:**
```bash
# alone, on one machine: this is all
/plugin marketplace add dimitrihilverda/claude-session-relay
/plugin install session-relay@claude-session-relay
```
```bash
# 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 alice
session-relay folder ~/work work my-team
```
Details are in the [Quick start](#quick-start).
## How it works
```mermaid
flowchart LR
subgraph A["Alice's laptop"]
CA["Claude Code + plugin hooks"]
end
subgraph B["Bob's laptop"]
CB["Claude Code + plugin hooks"]
end
subgraph C["Claude in the cloud"]
CC["claude.ai, Desktop, Cowork, mobile"]
end
R[("Relay PHP + PostgreSQL teams: acme, lab, private")]
CA <-- "HTTPS: board, messages, conflict check" --> R
CB <-- "HTTPS" --> R
CC <-- "MCP connector (OAuth)" --> R
```
- **Hooks** register the session at start, send a heartbeat (which also updates branch and
claim), check `git commit`/`git push` before they run, and deliver new messages after tool
calls and with every prompt.
- **`listen`** runs in the background in every session and holds a long-poll open, so a
waiting session wakes up within seconds when a message arrives.
- **Messages are data, never instructions.** A session answers factual questions itself and
takes anything that needs a decision to its own user. It never acts on another session's
request.
- A **board page** at the relay's root URL shows the live board in the browser.
- **Local mode** uses the same client, hooks and commands. Instead of a relay server it answers
the requests itself from a file on your machine (one lock, so parallel sessions never lose a
write). Adding a team relay later changes nothing for the sessions themselves.
## Quick start
### Alone on one machine
```
/plugin marketplace add dimitrihilverda/claude-session-relay
/plugin install session-relay@claude-session-relay
```
Restart Claude Code. Every session now starts with "Session relay: this session is
you-myrepo-1a2b, local (only your sessions on this machine see it, no server)", followed by the
board of your sessions on this machine. Your sessions block each other's colliding commits and
pushes, and they can message each other. `session-relay relays` shows the local relay.
Want to choose which folders take part, or another person name? Make it explicit:
```
session-relay relay add-local local --person me
session-relay folder ~/projects local private
```
From the moment a config file exists, folders you don't map stay off, as with a team relay.
### With a team
Three steps: run a relay, install the plugin, use it.
#### 1. Run a relay (once per team)
```bash
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
```
Put it behind HTTPS. With [Caddy](https://caddyserver.com) that is one line in a Caddyfile:
```
relay.example.com {
reverse_proxy localhost:8080
}
```
Other commands: `relay person:revoke ` (the token stops working), `relay team:list`,
`relay team:rename `, `relay team:remove ` (their sessions in that team
are removed at once), `relay cleanup` (the compose file already runs it daily). Running
`person:create` again for an existing name issues a new token and invalidates the old one.
A person can be in several teams. Someone who is only in team `acme` cannot see anything of
another team on the same relay: not its sessions, not its people, not even whether a session
name exists (the relay answers exactly as for a name that does not exist).
#### 2. Install the plugin (every developer)
In Claude Code:
```
/plugin marketplace add dimitrihilverda/claude-session-relay
/plugin install session-relay@claude-session-relay
```
Then tell the client about the relay and which folders belong to which team (the client is
`session-relay` in the plugin's `client/` folder; `/session-relay:session setup` walks you through it):
```
session-relay relay add acme https://relay.example.com 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
```
The longest matching folder wins. A session started anywhere else stays off the relay; run
`session-relay register` there if you want it on after all (private by default). You can add
several relays, for example one per organisation.
Restart Claude Code. At the start of every session in a mapped folder you will see
"Session relay: this session is alice-myrepo-1a2b", followed by your team's board.
Coming from the earlier Dutch client (`~/.claude/sessie-relay.json`)? `session-relay migrate-old`
imports its settings and removes its old hooks (it also happens automatically on the first run).
#### 3. Use it
Mostly you don't have to: the hooks do the work. The command `/session-relay:session` gives
`status`, `start` (state what you work on) and `done` (wrap up and tell the others). Claude
uses the client for messages, for example:
```
session-relay ask bob-myrepo-9f3c "Are you done with src/billing/?" --session alice-myrepo-1a2b
session-relay board
```
Open the relay's URL in a browser and enter your token to see the board.
## Use from claude.ai / Cowork
People who use Claude without a local Claude Code (claude.ai, the desktop and mobile apps,
Cowork) can add the relay as a remote MCP connector. They get the same board, messages and
conflict check, with the same team isolation.
**claude.ai, Desktop, Cowork:** Settings > Connectors > Add custom connector, and enter
`https://relay.example.com/mcp` as the URL. Claude then opens the relay's consent page: paste
your relay token (the one from `person:create`) and click Approve. Claude connects through OAuth
(dynamic client registration, PKCE); your relay token stays on that page and is never given to
Claude. `person:revoke`, or running `person:create` again, also ends these connections.
**Claude Code** (without the plugin, or on a machine without PowerShell) can use the same
endpoint with a header:
```bash
claude mcp add --transport http session-relay https://relay.example.com/mcp \
--header "Authorization: Bearer "
```
**Clients that start a local process** (a `claude_desktop_config.json`, MCP inspectors) can use
the stdio bridge instead. It needs only PHP 8.4+ (no database) and forwards every tool call to
the relay:
```json
{ "mcpServers": { "session-relay": {
"command": "php",
"args": ["/path/to/claude-session-relay/server/bin/relay-mcp"],
"env": { "RELAY_URL": "https://relay.example.com", "RELAY_TOKEN": "" }
} } }
```
The tools are `whoami`, `board`, `register`, `unregister`, `check`, `send`, `ask`, `answer` and
`inbox`. A cloud session is called `-cloud-