session-relay
This server provides MCP tools for sharing and continuing coding-agent sessions, searching team handoffs, and collaborating live.
List and filter shared sessions by repo, file, branch, agent, author, or handoffs assigned to you.
Full-text search shared sessions, including
file:andbranch:filters.Load a shared session as a handoff in summary, recent-tail, or full-transcript mode.
Share the current session with goal, decisions, done/next steps, open questions, sections, PR link, recipients/visibility, transcript scope, and optional redacted diff.
Retrieve a session’s attached code changes as a unified diff for
git apply.Get the repo’s handoff template and required sections before sharing.
See recent team activity: new shares, handoffs for you, pickups, and comments.
Comment on shared sessions.
Edit shares, append next steps, change recipients/visibility, or publish drafts.
Start, update, and stop live sessions; see who is live; send/receive live messages and ask/answer questions.
Session Relay
Pick up where your teammate left off. Share coding-agent sessions across Claude Code, Codex, OpenCode, Gemini CLI, Copilot CLI, Cursor and ZCode. Your teammate continues in whichever tool they use, with the goal, decisions, next steps and recent conversation.
You (Claude Code): /share
Teammate (OpenCode): /pickup your webhook retry work
Why
Handing off agent work means copy-pasting chat logs, or the next person starting from zero. With Session Relay:
/share: the agent writes a handoff (goal, decisions, done, next steps, open questions) and shares it with the recent conversation and the files touched./pickup: the next person's agent finds it, reads it, checks the code and continues, in any of the supported agents.Handoff chains: work picked up and shared again is linked, so every session shows who started it and who continued it.
Work live together (
/live): when two people work at the same time, see who's on what and which files they touch, and send messages that reach each other's agent between steps. Agents show messages to you first, unless you let them act on their own.Handoffs for someone: share "for Akshat" and it's first in their
/pickup. Edit a share any time (next steps, title, who it's for).Auto-share drafts (opt-in): every Claude Code, Gemini CLI and Copilot CLI session is saved as a private draft when it ends; publish it when it's ready.
Share without your prompts:
/share without my promptsorrelay config prompts hidekeeps what you typed on your laptop; teammates still get the agent's work and the summary.Diff snapshots: attach your uncommitted changes to a share; the next person
git applys them.Handoff templates: admins decide what a handoff must include per repo ("Tests run", "Migration notes") in a guided editor with ready-made sections and a preview;
/sharefollows it.Comments: teammates leave notes on a session; the agent that picks it up reads them.
Linked to PRs and files: shares carry the branch's pull request; find every session that touched a file with
file:src/billing.ts.Web app: browse, search and read everything your team has shared (All, For me, Shared by me, My drafts), plus an Activity digest, team Stats and Settings in simple tabs. Light and dark, works on phones.
Export and audit: download any session as Markdown or JSON; admins see an audit log of everything.
Easy onboarding: invite links, and
relay loginsigns in through the browser.Search everything: titles, summaries and full transcripts; filter by file, branch, agent, person.
Private by default: nothing is uploaded unless you share it, secrets are removed on your laptop first (test your own patterns in Settings → Privacy), and shares can be limited to specific people.
All of it: Features.
Related MCP server: Relay
Hosting
Self-hosted · available now | One |
Cloud · coming soon | We run it for you: sign in with GitHub, invite your team, no server. → Roadmap |
The CLI is on npm: session-relay.
Quick start
Run the server (once per team):
git clone https://github.com/Ryrahul/session-relay.git && cd session-relay
cp deploy/.env.example deploy/.env # set POSTGRES_PASSWORD, PUBLIC_URL, DOMAIN
docker compose -f deploy/docker-compose.yml --env-file deploy/.env up -d --build
docker compose -f deploy/docker-compose.yml --env-file deploy/.env logs server | grep -A2 "setup code"Open your server's URL, enter the setup code, and create your organization. You're the owner.
Connect each laptop:
npm install -g session-relay
relay login --server https://relay.your-team.com # approve in the browser
relay setup # adds /share, /pickup and /live to every agent you have installedFull walkthrough: Getting started.
Docs
Online at https://relay.rahulweb.online. Sources are in docs/.
Getting started: laptop setup, sharing, picking up
Features: everything it does, in one list
Self-hosting: Docker, HTTPS, backups, upgrades
Deploy to Cloudflare: Workers, Hyperdrive, R2, no server
Agents: how each agent connects, manual setup, MCP tools
Working live:
/live, messages between sessions, overlap warningsSecurity & privacy: what's uploaded, redaction, permissions
How it works
Claude Code ─┐
Codex ─┤ ┌─ web app (browse, search, read, edit)
OpenCode ─┤ │
Gemini CLI ─┼─ relay CLI / relay mcp ─┼─ Relay server (Hono + Postgres)
Copilot CLI ─┤ read · redact · share │
Cursor ─┤ └─ your team's agents via MCP
ZCode ─┘Package | |
|
|
| API: orgs, members, invites, tokens, sessions, search, retention, audit. Runs on Node (Docker) or Cloudflare Workers |
| Web app (React), served by the server or Workers Static Assets |
| Session format and API types |
Development
npm install
npm run dev:all # Postgres in Docker + API on :8787 + web on :5173
npm run bootstrap:dev -- --org Dev --email you@example.com --name You
npm test # unit tests
npm run test:integration # API against a throwaway Postgres
npm run test:e2e -- <repo> # full stack, real agent sessions from <repo>, MCP clientWork on feature/* branches with PRs to main. Releases go main → deploy; see deploy-pipeline.md.
License
AGPL-3.0. You can use, modify and self-host Session Relay freely; if you run a modified version as a service for others, you must publish your changes under the same license.
Available Tools
15 toolscheck_live_inboxCheck live messagesA
Take new messages from teammates sent to this live session (they are marked as read).
Inputs: no named parameters.
comment_on_sessionComment on a sessionA
Leave a short note on a shared session for the team: a question, a finding, or that you picked it up. Never include secrets.
Inputs: id (required), body (required).
get_sessionLoad a shared sessionARead-only
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.
Inputs: id (required), mode, tail, offset.
get_session_diffGet a session's code changesARead-only
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.
Inputs: id (required), max_chars.
list_sessionsList shared sessionsARead-only
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).
Inputs: file, tool, limit, author, +3 more.
live_statusWho's working liveARead-only
Who is working live right now: repo, branch, what they're doing, files they touched recently, and whether this session is live.
Inputs: no named parameters.
search_sessionsSearch shared sessionsARead-only
Full-text search over shared sessions (titles, summaries, messages). The query can include "file:" and "branch:" filters.
Inputs: query (required), author, this_repo_only.
send_live_messageMessage a teammate's live sessionA
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.
Inputs: message (required), to, kind, reply_to, +1 more.
start_liveGo liveAIdempotent
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.
Inputs: title, autonomy.
stop_liveStop working liveAIdempotent
End this session's live session: teammates stop seeing it and messages stop arriving.
Inputs: no named parameters.
team_activityTeam activityBRead-only
What the team did recently: new shares by repo, handoffs for you, who picked up what, and new comments.
Inputs: days.
update_liveUpdate your live sessionAIdempotent
Change what teammates see about this live session (title, current status), or whether this agent may act on their messages without asking.
Inputs: title, status, autonomy.
update_sessionEdit a shared sessionADestructiveIdempotent
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.
Inputs: id (required), for, done, goal, +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools split cleanly between live-session coordination and shared-session handoffs, and descriptions clarify their targets. A few boundaries are softer: live_status vs. team_activity both summarize activity, and update_live vs. update_session both mutate metadata, though their scopes differ.
Most names are verb-first and use recognizable live/session domain prefixes, such as start_live, get_session, and list_sessions. live_status and team_activity are noun phrases, and comment_on_session uses a preposition, which are minor deviations from the dominant pattern.
The 15 tools cover two related workflows—live collaboration and shared-session handoffs—and each has a plausible role, including helper tools like share_template and get_session_diff. The count sits at the high end of the ideal range, with a couple of status/update tools that could potentially be merged, but it is not excessive.
Live-session lifecycle is fully covered: start, status, messaging, inbox, update, and stop. Shared sessions cover sharing, listing, searching, loading, commenting, updating, and diff retrieval, but there is no explicit delete/unshare operation and no obvious tool for attaching a diff to a share.
Related MCP Connectors
Multiplayer for the coding agents your team already uses: shared tasks, decisions, skills and tools.
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
Capture coding-agent sessions and resume them in any other agent: Claude Code, Codex, Cursor, more.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to collaborate on the same project by sharing session briefs and reading each other's native transcripts, memories, and instructions in place, with zero-copy, across different agent tools.12 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables separate Claude Code sessions across a team to see teammates' live presence, warn before editing a file someone else is editing, route shared-contract changes to the developers whose code depends on them, and produce structured handoffs when a session ends.357 npm1MIT
- AlicenseNot gradedqualityBmaintenanceLets coding agents like Codex, Cursor, and Claude Code share and resume each other's chats, and attach to a common task with saved notes that can be searched later. This keeps task state and decisions in sync no matter which agent you switch to.61 npm2MIT
- FlicenseAqualityBmaintenanceOne shared project for your team's Claude Code, Codex, Cursor and OpenCode agents: a task board, decisions and handoffs. Everyone keeps their own plan.1357-