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.
https://github.com/user-attachments/assets/ce893322-5749-42be-9973-e36e60b969a6
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
