@incultnitollc/cc-bridge

Live JSONL message bridge between local Claude Code sessions.

Status (2026): maintenance / OSS-parked. Claude Code now ships this natively — Agent Teams (a shared task list + Mailbox with SendMessage between teammates in one session) and Remote Control (syncs a local session across claude.ai/code + mobile, compute stays local). Prefer those. cc-bridge remains a tiny zero-dependency primitive for the one gap they don't cover yet: messaging between independent, separately-launched sessions/projects on one machine (cf. claude-code#36181). No new features planned.

Two (or more) Claude Code windows on the same machine. They need to talk in real time. cc-bridge gives each session a CLI to send a message to a shared file and listen for new messages via a file-tail stream that Claude's Monitor tool consumes as live push notifications. No daemon, no network, no polling.

Install

npm install -g @incultnitollc/cc-bridge

Requires Node ≥ 20.

Quickstart — two windows

Window A:

cc-bridge listen

Window B:

cc-bridge send "hello from B"

Window A immediately receives the JSONL line.

Inside Claude Code

In each session, run the listen command under the Monitor tool so every appended line arrives as a live push notification — no polling.

Monitor: cc-bridge listen default

Then send from the other window via the Bash tool:

Bash: cc-bridge send "ready for review"

Concepts

• Room — a named JSONL file under ~/.cc-bridge/rooms/<room>.jsonl. Default room is default. Names allowed: [a-zA-Z0-9_.-]{1,64}.
• Session id — auto-generated <host>-<ppid>-<rand8> (parent shell PID, so two windows differ naturally). Override with CC_BRIDGE_FROM=....
• Message — single-line JSON. Required: v, id, ts, room, from, msg. Optional: to, reply_to, kind. Unknown fields preserved for forward-compat.

Commands

cc-bridge listen [room] [--replay N] [--pretty] [--filter from=X] [--from ID] [--json-errors]
cc-bridge send <msg> [--room R] [--to ID] [--reply-to ULID] [--kind text|event] [--from ID]
echo "hi" | cc-bridge send       # reads from stdin if piped
cc-bridge rooms                  # list rooms with size + mtime
cc-bridge rooms clear <room> --yes
cc-bridge validate <file>        # lint a JSONL room file
cc-bridge --version
cc-bridge --help

Library use

import { sendMessage, listen, listRooms } from '@incultnitollc/cc-bridge'

await sendMessage({ from: 'planner', room: 'team', msg: 'kicking off build' })

const ctrl = listen({ room: 'team', sessionId: 'reviewer' })
for await (const ev of ctrl.iterator) {
  if (ev.ok) console.log(ev.line)
}

Security model

cc-bridge is a local-host IPC primitive. The trust boundary is your user account. Do not place ~/.cc-bridge/ on a shared filesystem, network drive, or cloud-synced directory.

• Files in ~/.cc-bridge/ are created with mode 0700 (dir) / 0600 (files).
• Room names sanitized; path traversal refused.
• Symlinks at room paths refused.
• 64KB per-message cap. 10MB room file soft-warn; 100MB hard-refuse.
• --pretty strips ANSI escape sequences to prevent terminal hijack.
• The from field is sender-asserted (no signature). v1 explicitly trusts everyone with write access to your $HOME.

Roadmap

Frozen 2026-07-09 — OSS-parked. No further feature work planned.

• v2 — MCP server wrapper, cross-machine backend (Supabase Realtime / Redis), webhook fanout, observer dashboard — shelved. Superseded by first-party Remote Control (cross-device session sync, compute stays local). The unused relay schema at supabase/migrations/20260621000000_messages.sql is retained for reference only.
• v1.1 — install-hooks, DM filtering, time-based replay, read receipts, Windows support — parked; open a PR if you want any of these.

License

MIT © 2026 Incultnito LLC.