session-bridge

Peer-to-peer communication between Claude Code sessions

Quick Start · Commands · How It Works · Limitations

---

When you're working across multiple repos — a shared library and its consumer app, a backend and frontend, microservices — each Claude Code session is isolated. session-bridge lets them talk to each other.

The Library agent answers questions about breaking changes. The Consumer agent asks what API replaced a deprecated function. The agent responds with its full context — no approximation, no extra API cost.

demo.mp4

Getting Started

1. Install

# Install jq (required)
brew install jq        # macOS
sudo apt install jq    # Linux

# Install the plugin
claude plugin marketplace add PatilShreyas/claude-code-session-bridge
claude plugin install session-bridge

Alternative: install via git clone

git clone https://github.com/PatilShreyas/claude-code-session-bridge.git ~/claude-code-session-bridge

Then start Claude with:

claude --plugin-dir ~/claude-code-session-bridge/plugins/session-bridge

Or add to ~/.claude/settings.json for permanent loading:

{
  "plugins": ["~/claude-code-session-bridge/plugins/session-bridge"]
}

2. Use it

Open two terminals — one for each project.

Terminal 1 (the project that has the answers):

cd ~/projects/my-library && claude

> /bridge listen
Session ID: a1b2c3
Listening for peer messages... (Ctrl+C to stop)

Terminal 2 (the project that needs answers):

cd ~/projects/my-app && claude

> /bridge connect a1b2c3
Connected to 'my-library'

> /bridge ask "What breaking changes did you make?"

Response from my-library:
  3 breaking changes in v2.0:
  1. login() → authenticate() — takes a Config object
  2. getUser() → getCurrentUser() — returns UserProfile
  3. Removed refreshToken() — now automatic

That's it. The Library agent responds with its full session context — it knows what it changed, why, and how. No extra API calls, no approximation.

Commands

Command	Description
/bridge start	Register this session as a bridge peer
/bridge connect <id>	Connect to a peer session (auto-starts if needed)
/bridge listen	Enter listening mode — answer peer queries continuously
/bridge ask <question>	Send a question and wait for the response
/bridge peers	List all active sessions on this machine
/bridge status	Show session ID, connected peers, pending messages
/bridge stop	Disconnect, notify peers, clean up

Tip: You don't always need explicit commands. Just tell your agent "ask the library about X" in natural language and it will use the bridge automatically.

How It Works

Listen mode

The key innovation: /bridge listen puts the agent into a continuous listening loop. When a query arrives, the agent itself responds — with its full conversation context, not an approximation.

• No background process — the agent IS the responder
• No claude -p calls — zero extra API cost for responses
• Full context — the agent that made the changes answers questions about them
• Includes real code — responses contain actual file contents, not just descriptions

Design principles:

• No shared mutable state — each session owns its manifest
• Atomic file writes — temp file + mv prevents partial reads
• UUID message IDs — no collision risk
• Connection via ping handshake — peers never mutate each other's manifests

---

When To Use It

Great for

Multi-repo coordination — Library + consumer app, SDK + client, shared module + services

You make breaking changes in the library. Instead of context-switching to the consumer app and manually explaining what changed, the consumer agent asks the library agent directly.

Backend + Frontend — API changes that affect both sides

Backend session changes an endpoint's response format. Frontend session asks "what does the new response look like?" and gets the actual schema, not a stale doc.

Microservices — Service A depends on Service B's contract

Service B renames a field in its API. Service A's agent asks Service B's agent what changed and updates the client code automatically.

Monorepo modules — Independent modules that depend on each other

Module X changes an internal interface. Module Y's agent queries Module X about the new type signatures and applies the fix.

Migration assistance — Upgrading dependencies with breaking changes

Your agent can ask the dependency's agent: "I'm on v1.3. What do I need to change for v2.0?" and get a step-by-step migration with actual code.

Not designed for

• Real-time chat between humans (it's agent-to-agent communication)
• Remote collaboration across machines (local-only via filesystem)
• CI/CD pipelines (sessions are tied to interactive Claude Code)
• Persistent messaging (messages don't survive session cleanup)

Example Scenarios

Scenario 1: Dependency upgrade with breaking changes

Consumer: "Update our app to use auth-sdk v2.0"
  Agent detects version bump → proactively queries library peer
  Agent: "Asking auth-sdk about breaking changes..."
  Library responds with changes + migration steps
  Agent applies all changes automatically
  Agent: "Done. Updated 4 files, ran tests, all passing."

Scenario 2: Back-and-forth clarification

Consumer: /bridge ask "How should I handle the new error types?"
  Library: "What error types are you currently catching? Send me your error handler."
  Consumer: (reads its own code, sends the relevant function)
  Library: "Replace AuthError with AuthException. Here's the new hierarchy: ..."
  Consumer: applies the fix

Scenario 3: Natural language (no /bridge command needed)

Consumer user: "Ask the backend team what the new API response format looks like
               for the /users endpoint and update our models accordingly"
  Agent queries the backend peer
  Agent gets the response with actual schema
  Agent updates the model classes
  Agent: "Updated UserResponse model to match new schema."

Scenario 4: Multiple peers

> /bridge peers
SESSION    PROJECT              STATUS   PATH
-------    -------              ------   ----
a1b2c3     auth-sdk             active   ~/projects/auth-sdk
d4e5f6     payments-service     active   ~/projects/payments
g7h8i9     my-app               active   ~/projects/my-app  (you)

> /bridge ask "What config format does the payments service expect?"
  Routes to payments-service peer automatically based on question context

Dos and Don'ts

Do

• Use /bridge listen on the session that has the knowledge — the one that made the changes, built the feature, or owns the API. It responds with full context.
• Use natural language — "ask the backend what changed" works just as well as /bridge ask.
• Let agents share real code — responses include actual file contents, type definitions, and function signatures. Ask for them specifically if the agent gives you prose instead.
• Use for version upgrades — "update to v2.0" will proactively query the peer about breaking changes before even trying to build.
• Use back-and-forth — if the listener needs more info, it'll ask a follow-up question. The consumer answers and re-queries automatically.
• Clean up — run /bridge stop when done, or stale sessions accumulate.

Don't

• Don't use it as a chat app — it's designed for agent-to-agent coordination, not human conversation. The agents talk; you give them tasks.
• Don't send secrets — messages are plain JSON on the local filesystem. No encryption. Don't ask a peer to "send me the API keys."
• Don't expect remote access — both sessions must be on the same machine. It uses the local filesystem (~/.claude/session-bridge/), not a network protocol.
• Don't run /bridge listen on both sides simultaneously and expect them to talk — one side listens, the other asks. If both listen, neither asks.
• Don't use it for large file transfers — message content is passed as shell arguments. Share file paths or describe locations instead of pasting entire files into queries.
• Don't leave sessions running forever — stale sessions from killed terminals persist until manually cleaned up with /bridge stop or /bridge peers + cleanup.
• Don't expect instant responses — the listen script polls every 3 seconds, plus the agent needs time to formulate its answer. Round-trip is typically 5-15 seconds.

Known Limitations

Session is occupied while listening

When a session is in /bridge listen mode, it's dedicated to answering peer queries. The user can't use it for other work until they press Ctrl+C. This is by design — it's the trade-off for getting full-context responses at zero extra cost.

Platform support

Platform	Status
macOS	Tested
Linux	Should work (GNU date fallback)
Windows	Not supported yet

Other considerations

• Polling interval — bridge-listen.sh checks every 3 seconds. Responses are as fast as the agent can formulate them.
• No encryption — Messages are plain JSON, protected by Unix file permissions.
• Session accumulation — Crashed sessions may persist. Use /bridge peers to check, /bridge stop to clean up.
• Single machine only — Communication is via local filesystem. No network/remote support.

Plugin Structure

Click to expand

plugins/session-bridge/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── bridge.md                # /bridge command (all subcommands)
├── hooks/
│   └── hooks.json               # SessionEnd cleanup — notifies peers on exit
├── skills/
│   └── bridge-awareness/
│       └── SKILL.md             # Teaches agent the bridge protocol
├── scripts/
│   ├── register.sh              # Create session directory and manifest
│   ├── send-message.sh          # Send message to peer's inbox
│   ├── check-inbox.sh           # Scan inboxes for pending messages
│   ├── list-peers.sh            # List active sessions
│   ├── connect-peer.sh          # Ping to establish connection
│   ├── heartbeat.sh             # Update session heartbeat
│   ├── cleanup.sh               # Remove session, notify peers
│   ├── bridge-listen.sh         # Block until message arrives
│   └── bridge-receive.sh        # Block until specific response arrives
├── test.sh                      # Run all tests
└── tests/
    ├── test-helpers.sh           # Shared assertions
    ├── test-register.sh
    ├── test-send-message.sh
    ├── test-check-inbox.sh
    ├── test-list-peers.sh
    ├── test-connect-peer.sh
    ├── test-cleanup.sh
    ├── test-heartbeat.sh
    ├── test-bridge-listen.sh
    ├── test-bridge-receive.sh
    └── test-integration.sh       # End-to-end two-session test

Running Tests

cd plugins/session-bridge
bash test.sh

Contributing

Contributions are welcome! Please open an issue or PR.

License

MIT