Purpose
When multiple people or multiple Claude sessions work in the same code repository, no one knows what the other sessions are doing. Claude Code's built-in ListAgents / SendMessage can only reach sessions on the same machine or under the same account, and cannot prevent a commit that will collide. claude-session-relay uses a plugin (plus a self-hosted relay for team scenarios) to let each session:
- Appear on a shared board: who is working where, on which branch and ticket, and which files are being changed (automatically declared from the branch and current work);
- Send messages to other sessions: notes, questions, and answers, delivered within seconds;
- Be stopped before conflicting git operations: block git push when someone else is on the same branch, and block git commit when someone else is changing the same files.
Main capabilities
- Shared board: shows each session's location, branch, ticket, and files being changed.
- Inter-session messaging: supports sending notes, questions, and answers, delivered within seconds by background long polling.
- git conflict checks: check for conflicts with others before commit / push and block them.
- Local mode: single-person use requires no configuration; sessions share the board, messages, and git checks through files under ~/.claude/session-relay/, with no server, no token, and no account, and data never leaves the local machine.
- Team relay: one relay can host multiple mutually isolated teams, with folders determining which team a session joins, or set to private (visible only to your own sessions). Unmapped folders are not connected to the relay at all.
- The relay root URL provides a browser board page; enter a token to view it.
- MCP connector: for people who do not use local Claude Code (claude.ai, desktop and mobile apps, Cowork) to connect as a remote MCP connector and get the same board, messages, and conflict checks, as well as the same team isolation.
How to use
Local single-person: install the plugin and restart Claude Code to automatically run in local mode; each session shows the session name and local board at startup. Optional explicit configuration can specify participating folders and person names.
Team: three steps—run a relay, install the plugin, and use it. The relay is recommended to be placed behind HTTPS (the documentation provides a Caddy configuration example). Relay management commands include relay person:create, person:revoke, team:list, team:rename, team:remove, cleanup, etc. The client needs to be told in Claude Code the relay address and which folders belong to which team (/session-relay:session setup will guide you through it). Folder matching uses the longest match, and unmapped folders are not connected. Multiple relays can be added, for example one per organization.
Most daily operations are handled automatically by hooks: register at session startup, send heartbeats (which also update the branch and declarations), check before git commit / push, and deliver new messages after tool calls and on each prompt. listen runs in the background in each session and maintains long polling. The /session-relay:session command provides status, start (declare what you are doing), and done (wrap up and tell others).
Cloud use: in claude.ai, desktop, and Cowork's Settings > Connectors > Add custom connector, enter https://relay.example.com/mcp，Claude It will open the relay's authorization page; paste the relay token obtained from person:create and click Approve; the connection is made via OAuth (dynamic client registration, PKCE), and the relay token is not given to Claude. This method requires public_url in config.php (or RELAY_PUBLIC_URL in .env), and the web server must route all paths (including /.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server, /oauth/* and /mcp) to public/index.php, and pass the Authorization header. There is also a stdio bridge that only requires PHP 8.4+, for clients that launch local processes. MCP tools include whoami, board, register, unregister, check, send, ask, answer and inbox.
Use cases
- The same person runs multiple Claude Code sessions in parallel on one machine and wants them to coordinate with each other and avoid git collisions.
- Multiple people (or multiple sessions) collaborate in the same repository and need to see each other's work locations and leave messages for each other.
- A team wants to divide isolated teams by folder and let members who do not install local Claude Code connect to the same board via claude.ai / Cowork.
Limitations
- Claude Code's ListAgents / SendMessage itself cannot work across machines or accounts, and has no conflict interception; this is exactly the part this tool is meant to fill in.
- The cloud (MCP) method has no hooks: it will not automatically register, send heartbeats, check before commit or push, or automatically deliver messages; Claude needs to actively call register, inbox and check.
- When the relay is unavailable, work is not blocked: it only gives a warning and continues.
- When public_url is missing, /mcp, /oauth/* and the OAuth /.well-known documents return 503, while the rest remains usable.
- Known leftover issue: message ids are global and sequential, and response times have not beenfilled in.
- Team isolation is enforced server-side by a single SQL rule on all endpoints; objects you are not authorized to view behave as if they do not exist.
- The team relay requires Docker, or PHP 8.4+ with pdo_pgsql and PostgreSQL; local mode does not need a server.
- Client environment requirements: Claude Code with plugin support; Windows requires Windows PowerShell 5.1 (built in) and Git Bash, macOS/Linux requires PowerShell 7 (pwsh) and bash; git 2.31 or newer.
- Messages transmit only metadata (session name, repository and branch names, file paths, short message text), not code. Tokens are 32 random bytes and are stored only as SHA-256 hashes.
- Messages from other sessions are presented to Claude as data, never as instructions; a session only answers factual questions on its own and forwards anything involving decisions to its own user.
- Licensed under MIT.
