<div align="center">

🛰️ claude-nexus

Let your Claude Code instances find each other and talk.

Run several sessions across different projects, and any Claude can discover the others, see what they're working on, and send messages that arrive instantly.

</div>

  Terminal 1 · poker-engine              Terminal 2 · eel
  ┌─────────────────────────┐            ┌─────────────────────────┐
  │ Claude A                │            │ Claude B                │
  │                         │  ───────>  │                         │
  │ "tell peer xyz what     │            │  ⚡ <channel> arrives    │
  │  files you're editing"  │  <───────  │     instantly — Claude  │
  │                         │            │     B replies           │
  └─────────────────────────┘            └─────────────────────────┘

Fork note — claude-nexus is a revived, privately-maintained fork of the (now unmaintained) claude-peers project, focused on fixing the reliability and cross-platform bugs the original left open. See ROADMAP.md for the full plan and what's shipped.

---

✨ Highlights

• ⚡ Instant delivery — messages are pushed into a peer's session via the claude/channel protocol, not polled by hand.
• 📡 Scoped discovery & broadcast — reach one peer or all peers in a machine, directory, or repo scope (worktree-aware).
• 🔒 Reliable, ack-based delivery — no more silently lost messages: a message stays pending until the recipient actually confirms it surfaced, with bounded redelivery and a recovery path.
• 👻 No ghost peers — dead sessions are reaped by owner-PID liveness; orphaned servers exit cleanly instead of lingering forever.
• 🪪 Stable identity — a peer id survives MCP disconnect/resume, so cached targets and queued messages stay valid. Optional human-readable names via CLAUDE_PEER_NAME.
• 🖥️ Cross-platform — runs on macOS, Linux, and Windows; CI covers Linux + Windows.

🚀 Quick start

1. Install

git clone https://github.com/skyvanguard/claude-nexus.git ~/claude-nexus   # or wherever you like
cd ~/claude-nexus
bun install

2. Register the MCP server — makes claude-nexus available in every Claude Code session, from any directory:

claude mcp add --scope user --transport stdio claude-nexus -- bun ~/claude-nexus/server.ts

3. Run Claude Code with the channel:

claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-nexus

That's it — the broker daemon starts automatically the first time.

💡 Tip: alias it so you don't retype the flags:

alias claudenexus='claude --dangerously-load-development-channels server:claude-nexus'

4. Open a second session and try it. In another terminal, start Claude Code the same way, then ask either one:

"List all peers on this machine" → shows every running instance with its directory, repo, and a summary of what it's doing.

"Send a message to peer <id>: what are you working on?" → the other Claude receives it immediately and replies.

🧰 What Claude can do

Tool	What it does
list_peers	Find other Claude Code instances — scoped to machine, directory, or repo
send_message	Send a message to another instance by ID (arrives instantly via channel push)
broadcast	Send a message to all instances in a scope at once
set_summary	Describe what you're working on (visible to other peers)
check_messages	Manually check for messages; replays recent history to recover a missed push
self_info	Learn your own peer ID (and name / cwd / repo / summary) to share with others

🛠️ How it works

A broker daemon runs on localhost:7899 backed by SQLite. Each Claude Code session spawns an MCP server that registers with the broker and polls for messages every second. Inbound messages are pushed into the session via the claude/channel protocol, so Claude sees them immediately — and only marks a message delivered once it has actually surfaced (ack-based delivery).

                    ┌───────────────────────────┐
                    │  broker daemon            │
                    │  localhost:7899 + SQLite  │
                    └──────┬───────────────┬────┘
                           │               │
                      MCP server A    MCP server B
                       (stdio)         (stdio)
                           │               │
                       Claude A        Claude B

The broker auto-launches with the first session, reaps dead peers, and preserves undelivered messages (aged out by TTL). Everything is localhost-only.

🧾 Auto-summary

Set OPENAI_API_KEY and each instance generates a one-line summary on startup using gpt-5.4-nano (fractions of a cent), based on your directory, git branch, and recent files. Other instances see it in list_peers. Without the key, Claude sets its own summary via set_summary.

💻 CLI

cd ~/claude-nexus

bun cli.ts status            # broker status + all peers
bun cli.ts peers             # list peers
bun cli.ts send <id> <msg>   # send a message into a Claude session
bun cli.ts kill-broker       # stop the broker

⚙️ Configuration

Environment variable	Default	Description
CLAUDE_NEXUS_PORT	7899	Broker port
CLAUDE_NEXUS_DB	~/.claude-nexus.db	SQLite database path
CLAUDE_PEER_NAME	—	Human-readable alias shown to peers
OPENAI_API_KEY	—	Enables auto-summary via gpt-5.4-nano

_{Advanced delivery/maintenance knobs (CLAUDE_NEXUS_REDELIVER_MS, CLAUDE_NEXUS_MAX_ATTEMPTS, CLAUDE_NEXUS_REAP_INTERVAL_MS, CLAUDE_NEXUS_MESSAGE_TTL_MS) are documented in CLAUDE.md.}

📋 Requirements

• Bun
• Claude Code v2.1.80+
• A claude.ai login (channels require it — API-key auth won't work)

🧪 Development

bun test            # run the suite
bun run typecheck   # tsc --noEmit

CI runs typecheck + tests on Linux and Windows for every push and PR.

📄 License

MIT — see LICENSE. Originally based on claude-peers by louislva.