dimitrihilverda/claude-session-relay

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).
If the relay is down, nothing is blocked: you get a warning and carry on.
**In short:**
Details are in the Quick start.
How it works
- **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
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:
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)
Put it behind HTTPS. With Caddy that is one line in a Caddyfile:
Other commands: relay person:revoke (the token stops working), relay team:list,