Enables teams to share coding-agent sessions, decisions, and conversation history across different AI clients like Claude Code and Cursor.
Also known as Ryrahul/session-relay, session-relay
- Stars
- 8
- Tools
- 15
- Downloads, 30 days
- —
- Latest version
- 0.7.0
- Last commit
- Oct 26, 2026
- License
- AGPL-3.0
What is Session Relay MCP?
Session Relay enables teams to share coding-agent sessions, decisions, and conversation history across different AI clients like Claude Code and Cursor. It exposes 15 tools, such as list_sessions, search_sessions, get_session.
Summary generated from the project's README
About Session Relay MCP server
Session Relay allows engineering teams to transfer coding-agent sessions, decisions, and conversation histories between different AI clients. It bridges the gap between tools like Claude Code, Cursor, Gemini CLI, Copilot CLI, and others. By using the relay MCP server, developers can hand off complex tasks to teammates, ensuring the next person understands the current goals and recent context.
To use this service, teams must host their own Session Relay server. After installing the package via npm, users run the setup command to integrate the MCP server and specific slash commands into their agents. The system includes privacy protections that strip API keys and passwords locally before any data is uploaded. Users can manage their shared work through a CLI that supports searching, editing, and exporting sessions in Markdown or JSON formats.
What you can do with it
- 1Handoff agent tasks to teammatesA developer can transfer a specific coding goal and recent conversation history to a colleague using the share command.
- 2Collaborate on sessions in real timeTeammates can monitor who is working on which files and send messages directly to an active agent session.
- 3Sync uncommitted code changesYou can attach your local uncommitted changes to a shared session so teammates can apply them to their own environments.
- 4Automate session draftingThe tool can automatically save sessions from various CLI agents as private drafts once a task finishes.
Written from the project's README. Every use case is checked against a quote from it.
How to install Session Relay MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Session Relay MCP in Claude Code
$ claude mcp add --env 'RELAY_TOKEN=<YOUR_RELAY_TOKEN>' session-relay -- npx -y session-relay mcpInstall Session Relay MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"session-relay": {
"command": "npx",
"args": [
"-y",
"session-relay",
"mcp"
],
"env": {
"RELAY_TOKEN": "<YOUR_RELAY_TOKEN>"
}
}
}
}Install Session Relay MCP in VS Code
.vscode/mcp.json
{
"servers": {
"session-relay": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"session-relay",
"mcp"
],
"env": {
"RELAY_TOKEN": "<YOUR_RELAY_TOKEN>"
}
}
}
}Install Session Relay MCP in VS Code CLI
$ code --add-mcp '{"name":"session-relay","type":"stdio","command":"npx","args":["-y","session-relay","mcp"],"env":{"RELAY_TOKEN":"<YOUR_RELAY_TOKEN>"}}'Install Session Relay MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"session-relay": {
"command": "npx",
"args": [
"-y",
"session-relay",
"mcp"
],
"env": {
"RELAY_TOKEN": "<YOUR_RELAY_TOKEN>"
}
}
}
}Install Session Relay MCP in Codex
$ codex mcp add session-relay --env 'RELAY_TOKEN=<YOUR_RELAY_TOKEN>' -- npx -y session-relay mcpInstall Session Relay MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.session-relay] command = "npx" args = ["-y", "session-relay", "mcp"] [mcp_servers.session-relay.env] RELAY_TOKEN = "<YOUR_RELAY_TOKEN>"
Install Session Relay MCP in Gemini CLI
$ gemini mcp add -s user -e 'RELAY_TOKEN=<YOUR_RELAY_TOKEN>' session-relay npx -- -y session-relay mcpInstall Session Relay MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"session-relay": {
"command": "npx",
"args": [
"-y",
"session-relay",
"mcp"
],
"env": {
"RELAY_TOKEN": "<YOUR_RELAY_TOKEN>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for session-relay 0.7.0 in an isolated container with no network and no keys. It answered and listed 15 tools.
Session Relay MCP tools 15
Read from the server with tools/listlist_sessionsRead-onlyList sessions teammates have shared. Defaults to the current repo; pass all_repos to see everything. for_me lists handoffs assigned to you (from any repo).
search_sessionsRead-onlyFull-text search over shared sessions (titles, summaries, messages). The query can include "file:<path>" and "branch:<name>" filters.
get_sessionRead-onlyLoad a shared session as a handoff: summary, decisions, next steps, files and conversation. mode "tail" (default) = summary + recent messages; "summary" = summary only; "full" = full transcript, paged with offset.
share_current_sessionActionShare the session you are in right now with the team. Write the summary yourself from the conversation: it is what teammates read first. Never include secrets.
get_session_diffRead-onlyThe uncommitted changes a teammate attached to a shared session, as a unified diff. Use it to see exact code state; to apply it, write it to a file and run `git apply`.
share_templateRead-onlyThe handoff template for the current repo: extra sections (some required) and instructions to follow when sharing. Call it before share_current_session.
team_activityRead-onlyWhat the team did recently: new shares by repo, handoffs for you, who picked up what, and new comments.
comment_on_sessionActionLeave a short note on a shared session for the team: a question, a finding, or that you picked it up. Never include secrets.
update_sessionActionChange a share you made (or any share, if you're an admin): title, summary fields, who it's for, the PR link or visibility. Summary lists you pass replace the old ones; use add_next to append next steps.
start_liveActionStart working live in this repo: teammates see what you're working on and which files you touch, and their messages reach you between steps. Lists who else is live here.
live_statusRead-onlyWho is working live right now: repo, branch, what they're doing, files they touched recently, and whether this session is live.
send_live_messageActionSend a short message to a teammate who is working live: it reaches their agent between steps. Use it to tell them about a change that affects them, ask a question, or answer theirs. Never include secrets.
| list_sessions | List sessions teammates have shared. Defaults to the current repo; pass all_repos to see everything. for_me lists handoffs assigned to you (from any repo). | Read-only |
| search_sessions | Full-text search over shared sessions (titles, summaries, messages). The query can include "file:<path>" and "branch:<name>" filters. | Read-only |
| get_session | Load a shared session as a handoff: summary, decisions, next steps, files and conversation. mode "tail" (default) = summary + recent messages; "summary" = summary only; "full" = full transcript, paged with offset. | Read-only |
| share_current_session | Share the session you are in right now with the team. Write the summary yourself from the conversation: it is what teammates read first. Never include secrets. | Action |
| get_session_diff | The uncommitted changes a teammate attached to a shared session, as a unified diff. Use it to see exact code state; to apply it, write it to a file and run `git apply`. | Read-only |
| share_template | The handoff template for the current repo: extra sections (some required) and instructions to follow when sharing. Call it before share_current_session. | Read-only |
| team_activity | What the team did recently: new shares by repo, handoffs for you, who picked up what, and new comments. | Read-only |
| comment_on_session | Leave a short note on a shared session for the team: a question, a finding, or that you picked it up. Never include secrets. | Action |
| update_session | Change a share you made (or any share, if you're an admin): title, summary fields, who it's for, the PR link or visibility. Summary lists you pass replace the old ones; use add_next to append next steps. | Action |
| start_live | Start working live in this repo: teammates see what you're working on and which files you touch, and their messages reach you between steps. Lists who else is live here. | Action |
| live_status | Who is working live right now: repo, branch, what they're doing, files they touched recently, and whether this session is live. | Read-only |
| send_live_message | Send a short message to a teammate who is working live: it reaches their agent between steps. Use it to tell them about a change that affects them, ask a question, or answer theirs. Never include secrets. | Action |
Show all 15 toolsShow fewer tools
check_live_inboxActionTake new messages from teammates sent to this live session (they are marked as read).
update_liveActionChange what teammates see about this live session (title, current status), or whether this agent may act on their messages without asking.
stop_liveActionEnd this session's live session: teammates stop seeing it and messages stop arriving.
| check_live_inbox | Take new messages from teammates sent to this live session (they are marked as read). | Action |
| update_live | Change what teammates see about this live session (title, current status), or whether this agent may act on their messages without asking. | Action |
| stop_live | End this session's live session: teammates stop seeing it and messages stop arriving. | Action |
Configuration
RELAY_TOKENSecretPersonal access token (srk_...) from Settings → Tokens. Optional if you ran relay login.
RELAY_SERVERURL of your team's Session Relay server. Optional if you ran relay login.
| Name | Description | |
|---|---|---|
| RELAY_TOKEN | Personal access token (srk_...) from Settings → Tokens. Optional if you ran relay login. | Secret |
| RELAY_SERVER | URL of your team's Session Relay server. Optional if you ran relay login. |
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubsession-relay
Share coding-agent sessions with your team across Claude Code, Codex, OpenCode, Gemini CLI, Copilot CLI, Cursor and ZCode. Run /share in one agent; a teammate runs /pickup in whichever agent they use and carries on with the goal, decisions, next steps and recent conversation.
npm install -g session-relay
relay login --server https://relay.your-team.com # approve in the browser
relay setup # adds the relay MCP server and /share, /pickup, /live to your agents
Then, in your agent:
/share
/share for bob
/pickup
/pickup alice's webhook retry work
/live # working at the same time: see who's on what, message their session
You need a Session Relay server for your team; see self-hosting. Cloud hosting is coming soon.
Commands
relay sessions |
Your local agent sessions for this repo |
relay share [--dry-run] |
Pick a session, choose what to include and who sees it |
relay share --no-prompts |
Leave your typed prompts out (relay config prompts hide to always do that) |
relay share --diff |
Attach your uncommitted changes; teammates git apply them after relay pull |
relay share --for <name> |
A handoff for a teammate (also --pr <url>; the branch's PR is found automatically) |
relay list, relay search "<q>" |
Shared sessions. --for-me, --file <path>, or file: / branch: in the query |
relay show <id>, relay pull <id> |
Read a session, or write .relay/handoff-<id>.md for your agent |
relay edit <id> |
Change your share: title, summary, next steps, who it's for, PR |
relay pr-comment <id> |
Post the session on its pull request |
relay setup --auto-share on |
Save each Claude Code, Gemini CLI and Copilot CLI session as a private draft when it ends; relay publish <id> shares it |
relay live start, relay live status |
Work live with teammates: who's on what and which files |
relay live send <name|everyone> "<text>" |
Message a teammate's live session; it reaches their agent between steps (also reply, inbox, watch, auto on|off, stop) |
relay setup --live on |
Hooks so live messages and file overlap warnings arrive in Claude Code and Gemini CLI by themselves |
relay template |
The handoff template for this repo |
relay export <id>, relay export --all |
Download a session (Markdown/JSON) or many (NDJSON) |
relay setup --tools gemini |
Connect one agent you installed later |
relay digest, relay stats |
What the team did lately; team stats |
relay comment <id> "<text>" |
Leave a note on a session (the next agent reads it) |
relay delete <id> |
Delete your share |
relay members, relay invite --link |
Your team; invite links (admins) |
relay setup |
Connect every agent you have installed |
relay mcp |
The MCP server your agents start |
Full reference: CLI docs.
Privacy
Nothing is uploaded unless you share it. API keys, tokens, passwords and private keys are removed on your machine before upload, and relay share --dry-run shows exactly what would be sent. See security & privacy.
License
AGPL-3.0-only
Session Relay MCP questions
How do I add Session Relay MCP to Claude Code?
Run claude mcp add --env 'RELAY_TOKEN=<YOUR_RELAY_TOKEN>' session-relay -- npx -y session-relay mcp in your terminal. Add --scope user to make it available in every project.
How do I add Session Relay MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Session Relay MCP provide?
It exposes 15 tools, including list_sessions, search_sessions, get_session, share_current_session, get_session_diff.
How do I share a session with a teammate?
You can use the /share command in your agent to share a session, and your teammate can use /pickup in their agent to continue the work.
Can I work on the same session at the same time as a teammate?
Yes, the /live command allows you to see who is working on what and message their session.
Is my private data safe when sharing sessions?
Nothing is uploaded unless you explicitly share it, and sensitive information like API keys and passwords are removed locally before upload.
How can I see exactly what data will be sent before sharing?
You can use the --dry-run flag with the share command to preview the content.