claude-session-bridge-mcp

Let two (or more) Claude Code sessions talk to each other — and optionally orchestrate themselves.

You open one Claude Code session for your backend and another for your frontend. Normally they know nothing about each other — when the backend changes an API, you copy-paste the result into the frontend session by hand.

This tool removes the copy-paste. A session sends its result; sibling sessions receive it automatically. Turn on the optional auto mode and a finished backend can wake the frontend to react — hands-off ping-pong — while you keep full control of the safety rails (no auto-commits, deploy gates, loop guards) and change every setting from inside Claude.

New here? Read top to bottom — every command is included. You don't need to understand the internals to use it.

Table of contents

• How to picture it

• Requirements

• Install (one time)

• Connect two sessions

  • Two ways to set the variables

  • Using tmux

• Send and receive messages

• Roles are just labels

• Run several projects at once

• Auto mode: the event spawner

  • Two drivers: tmux vs spawn

  • Configure and run

  • Safety rails

  • Sensitive roles are off by default

  • Never auto-commit (and how to allow it)

  • Be careful with auto-deploy

• Change settings from inside Claude

• Reference

Related MCP server: Claude Relay

How to picture it

Two simple ideas:

• Project = a chat room. Sessions launched with the same project name are in the same room and can talk. Different project name = different room, isolated.

• Role = your nickname in that room. backend, frontend, infra — any label you like. You address messages to a role.

Session 1   project "shop"  role "backend"  ┐
                                            ├─ room "shop" (they talk)
Session 2   project "shop"  role "frontend" ┘

Session 3   project "blog"  role "backend"  ─── room "blog" (separate, isolated)

There is no "connect" button. Launching two sessions with the same project name is connecting them.

Requirements

• Node.js 18+ — check with node --version

• Claude Code (the claude command) — check with claude --version

• tmux — recommended; the default auto-mode driver drives your live sessions through it. (Not needed if you only use the bus, or the spawn driver.)

Install (one time)

You do this once. Afterward you never edit these files again — the only thing that changes per session is two environment variables (explained next).

1. Get the code and build it.

git clone <this-repo-url> claude-session-bridge-mcp
cd claude-session-bridge-mcp
npm install
npm run build

2. Register the bridge. Run this inside a Claude Code session (so it targets that session's config dir — see the note):

npm link                  # optional: puts `session-bridge` on PATH
session-bridge install    # registers the MCP server + hooks
session-bridge doctor     # verify what's set up, and where

install merges the MCP server, the receive hook, and the block-git hook (blocks git commit/push/reset) into your active settings.json — idempotently, without touching your other settings. Add --no-block-git if you want sessions to commit on their own. (If session-bridge isn't on your PATH, run node /ABSOLUTE/PATH/dist/cli.js install.)

Work accounts / multiple profiles. Claude Code reads $CLAUDE_CONFIG_DIR/settings.json when that env var is set (common for a separate work login), otherwise ~/.claude/settings.json. This is the #1 reason "I edited settings and nothing changed" — you edited the wrong file. Running session-bridge install inside a session of a given profile targets the correct file automatically. Run it once per profile. Check with session-bridge doctor, which prints the active config dir.

Add to the right settings.json (replace /ABSOLUTE/PATH):

{
  "mcpServers": {
    "session-bridge": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/claude-session-bridge-mcp/dist/server.js"]
    }
  },
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [ { "type": "command",
        "command": "node /ABSOLUTE/PATH/claude-session-bridge-mcp/dist/hooks/recv.js" } ] }
    ],
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [ { "type": "command",
        "command": "node /ABSOLUTE/PATH/claude-session-bridge-mcp/dist/hooks/block-git.js" } ] }
    ]
  }
}

All hooks no-op safely in non-bridged sessions, so they're fine installed globally. That's the whole setup.

Connect two sessions

To put a session in a room, give it two values when you launch it:

# Terminal 1 — the backend of project "shop"
BRIDGE_PROJECT=shop BRIDGE_ROLE=backend claude

# Terminal 2 — the frontend of project "shop"
BRIDGE_PROJECT=shop BRIDGE_ROLE=frontend claude

Both used project shop, so they're in the same room and can talk.

Two ways to set the variables

Pick one — but don't mix them up; this is the #1 beginner mistake.

Way A — on the same line (simplest, recommended):

BRIDGE_PROJECT=shop BRIDGE_ROLE=frontend claude

The variables apply only to that one claude. Nothing to clean up.

Way B — set first, then launch. On separate lines you must use export:

export BRIDGE_PROJECT=shop
export BRIDGE_ROLE=frontend
claude

⚠️ The trap: BRIDGE_PROJECT=shop on its own line without export sets a shell variable claude will not see — the bridge silently won't connect. Use export (Way B), or put everything on one line (Way A).

Tip — make aliases so you don't retype this. In ~/.zshrc (or ~/.bashrc):

alias shop-back='BRIDGE_PROJECT=shop BRIDGE_ROLE=backend claude'
alias shop-front='BRIDGE_PROJECT=shop BRIDGE_ROLE=frontend claude'

Using tmux

tmux changes nothing about launching — each pane is its own shell, like a separate terminal. Set the variables in each pane and run claude:

tmux
 ├ pane 1:  BRIDGE_PROJECT=shop BRIDGE_ROLE=backend  claude
 ├ pane 2:  BRIDGE_PROJECT=shop BRIDGE_ROLE=frontend claude   ← same room as pane 1
 └ pane 3:  BRIDGE_PROJECT=blog BRIDGE_ROLE=backend  claude   ← different room

tmux matters most for auto mode: the default driver wakes these live panes automatically (see the spawner). A session launched inside tmux registers its pane on its own — no manual setup.

If you use export (Way B) in a pane and later launch a different project's claude in that same pane, the old export lingers. Prefer Way A inside tmux to avoid surprises.

Send and receive messages

Once two sessions share a room, this just works:

1. In the backend session, when you have something worth sharing:

   "Send the new /users response shape to the frontend session."

   It calls the bridge_send tool to deliver the message.

2. In the frontend session, the next time you type anything, the message is automatically added to its context — no copy-paste.

That's the default ("bus") mode: sending is deliberate (the model shares a real result, not a wall of text), and receiving is automatic on the next turn. You're still driving.

You can also be explicit in either session: "Check the bridge for new messages" (bridge_recv) or "Send this to infra: staging is ready" (bridge_send).

If a session finishes and has nothing worth sharing, it simply doesn't send — nothing hits the bus and any ping-pong ends naturally. Idle sessions don't spam the room.

Roles are just labels

A role is any string you want — not only backend/frontend. Add as many sessions to a room as you like:

BRIDGE_PROJECT=shop BRIDGE_ROLE=backend  claude
BRIDGE_PROJECT=shop BRIDGE_ROLE=web      claude
BRIDGE_PROJECT=shop BRIDGE_ROLE=infra    claude
BRIDGE_PROJECT=shop BRIDGE_ROLE=qa       claude

When sending, address a specific role (to: "infra") or broadcast to everyone else (to: "*"). A message addressed to frontend is delivered only to frontend — infra/qa never even see it, so they can't act on it by mistake. (Only to: "*" reaches everyone.) So a multi-step flow is natural:

backend finishes an API → tells web → web updates the UI → tells infra → infra redeploys.

Whether that chain runs automatically is up to the spawner below — and for deploys, read Be careful with auto-deploy first.

Run several projects at once

Use different project names; they never see each other's messages:

BRIDGE_PROJECT=shop BRIDGE_ROLE=backend  claude   # room "shop"
BRIDGE_PROJECT=blog BRIDGE_ROLE=frontend claude   # room "blog" — isolated

Isolation is structural (messages live under a per-project folder), so shop and blog can't cross over.

Auto mode: the event spawner

Everything above keeps you in the loop — a session acts only when you give it a turn. The event spawner is an optional background program (a daemon) that removes that step: when a role receives a message, the spawner wakes that role automatically to act on it, so the sides can ping-pong with no human in between. You run it in its own terminal; it's opt-in and easy to turn off.

Two drivers: tmux vs spawn

The driver decides how a role is woken:

Analogy: tmux taps an employee already at their desk; spawn hires a new temp for each task.

Why tmux is the default: it orchestrates the open sessions you're already working in, keeps their context, lets you watch and interrupt, and doesn't use claude -p (so it's unaffected by changes to headless/SDK billing). Use spawn when you can't run tmux or want isolated one-shot runs.

Configure and run

A role is only auto-woken once it's set up — out of the box the spawner does nothing, so you opt in role by role:

# tmux driver: just open the role's session inside tmux — its pane auto-registers.
# spawn driver: tell it where the role's code lives:
session-bridge spawner set shop backend cwd=/path/to/backend

session-bridge spawner on              # enable globally
session-bridge spawner off shop        # ...or per project
session-bridge spawner off shop web    # ...or one role
session-bridge spawner status          # inspect current config

(session-bridge is the CLI installed with this package. If it's not on your PATH, run node /ABSOLUTE/PATH/dist/cli.js spawner ....)

Run the daemon in its own terminal:

session-bridge spawner run             # foreground; Ctrl-C to stop
# or background it:
nohup session-bridge spawner run > ~/.claude/bridge/spawner.log 2>&1 &

Config is re-read on every event, so on/off and other changes take effect live — no restart needed.

Safety rails

Sensitive roles are off by default

infra and qa ship in defaultOffRoles — the spawner will not auto-wake them even when configured. You must opt them in by name.

Why? The sender chooses who a message goes to, and the sender is a language model. If it ever broadcasts (to: "*") or mis-addresses, infra/qa could receive a request not meant for them — and those roles do the riskiest things (deploys, releases, destructive tests). Keeping them off is a guarantee that does not depend on the model addressing correctly: a misrouted message just sits in the inbox until a human opens that session.

Turn them on (if you want full automation):

session-bridge spawner on shop infra      # explicit opt-in (required)

Read Be careful with auto-deploy first. To change the list, edit defaultOffRoles in <BRIDGE_ROOT>/spawner.config.json.

Never auto-commit (and how to allow it)

By default, auto-driven sessions can't commit. Two layers enforce it:

1. spawn driver: sessions launch with --disallowed-tools "Bash(git commit:*)" "Bash(git push:*)" .... Deny rules beat allow/bypass, so the model physically can't commit.

2. tmux driver (live sessions): those flags don't apply, so install the block-git PreToolUse hook (in Install). It denies git commit/push/reset in any session, however its turn was triggered.

A CLAUDE.md reminder ("don't commit") is a nice-to-have but not enough for autonomous loops — a model can drift. The hook/deny rules are the real guarantee.

If you WANT commit/push automation (some people do), opt out:

• Don't install the block-git hook, and

• Remove git entries from denyTools (session-bridge spawner config) for the spawn driver.

• Or narrow what's blocked with BRIDGE_BLOCK_GIT (a regex; e.g. allow commit but still block push).

⚠️ Auto-push is outward-facing and hard to undo. If you allow it, push to a feature branch and protect main (branch protection). Don't auto-push to main.

Be careful with auto-deploy

⚠️ Commits/pushes are blocked — but deploying is not git. kubectl apply, vercel deploy, terraform apply, an SSH deploy script — none are blocked by default, so an autonomous infra session could run them. Deploying is outward-facing and hard to undo; doing it with no human present is risky.

If you want infra in the loop, pick one:

1. Keep infra manual (default — it's off). Messages queue; you open the session and deploy yourself.

2. Block deploy commands (add them to denyTools or the block-git regex).

3. Automate only safe steps — staging/dry-run automatic, production manual.

Change settings from inside Claude

You don't have to edit JSON or remember CLI flags. The MCP server lets you read and change every automation setting from inside a Claude session — a dashboard, conversational or via /mcp.

Safety: admin-gated. Settings can only be changed from a session launched with BRIDGE_ADMIN=1 (your "control" session). Auto-driven sessions don't have it, so a runaway loop can't flip its own safety settings. Reading config is always allowed.

# your control / dashboard session
BRIDGE_PROJECT=shop BRIDGE_ROLE=control BRIDGE_ADMIN=1 claude

Two ways to drive it:

A. Just talk to it (the model calls the tools):

"Show the bridge config." · "Set frontend to auto." · "maxHops 3, driver tmux." · "Turn automation off."

B. /mcp prompts (slash commands that apply the change on the spot):

/mcp__session-bridge__show-config       show current settings
/mcp__session-bridge__set-mode          project, role, auto|manual
/mcp__session-bridge__configure-role    cwd / model / tmuxTarget
/mcp__session-bridge__set-driver        tmux | spawn
/mcp__session-bridge__automation        on | off  (master switch)
/mcp__session-bridge__set-limits        maxHops / rateLimitPerMinute

Pick one, fill the arguments, and it writes the change immediately (admin session only). The daemon picks it up live.

Reference

Tools (callable by a session)

CLI

# setup (targets the active config dir: $CLAUDE_CONFIG_DIR or ~/.claude)
session-bridge install [--no-block-git] [--config-dir <dir>]
session-bridge doctor

# inspect the bus (use any role as your identity)
BRIDGE_PROJECT=shop BRIDGE_ROLE=cli session-bridge roles
BRIDGE_PROJECT=shop BRIDGE_ROLE=cli session-bridge send frontend "hello"
BRIDGE_PROJECT=shop BRIDGE_ROLE=cli session-bridge tail 20
session-bridge root            # bus storage directory

# the spawner
session-bridge spawner set <project> <role> cwd=<path> [model=<m>] [tmuxTarget=<t>]
session-bridge spawner on  [project] [role]
session-bridge spawner off [project] [role]
session-bridge spawner status
session-bridge spawner run [--replay]

Environment variables

Optional: auto-send every turn

Off by default — deliberate bridge_send is preferred. To broadcast a session's last message automatically each turn, set BRIDGE_AUTOSEND=1 and add the Stop hook to settings.json (dist/hooks/send.js). Override the target with BRIDGE_SEND_TO. Noisier and more tokens than deliberate sends.

How it works (for the curious)

Messages and config are plain files under BRIDGE_ROOT:

~/.claude/bridge/
  spawner.config.json          automation settings (edited live)
  <project>/
    <role>.inbox.jsonl         append-only log of messages for that role
    .cursors/<role>.cursor     how many messages that role has read
    .sessions/<role>.pane      tmux pane id, for the tmux driver to find it

bridge_send appends to the recipient's inbox. The receive hook reads your inbox from your cursor forward, injects the new lines, and advances the cursor — so you never see a message twice. Isolation is just the per-project folder.

Tests

npm test             # MCP bus end-to-end
npm run test:config  # config dashboard + admin gate
npm run test:prompts # /mcp prompts apply changes (admin-gated)
npm run test:spawner # spawn-driver ping-pong + loop guard
npm run test:tmux    # tmux-driver ping-pong + loop guard
npm run test:real    # real two-session test using `claude -p`

License

MIT