<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_.

[![CI](https://github.com/skyvanguard/claude-nexus/actions/workflows/ci.yml/badge.svg)](https://github.com/skyvanguard/claude-nexus/actions/workflows/ci.yml)
![Platforms](https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-informational)
![Runtime](https://img.shields.io/badge/runtime-Bun-black?logo=bun)
![License](https://img.shields.io/badge/license-MIT-blue.svg)

</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`](./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`](https://code.claude.com/docs/en/channels-reference) 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**

```bash
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:

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

**3. Run Claude Code with the channel:**

```bash
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:
> ```bash
> 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

```bash
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` |

<sub>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`](./CLAUDE.md).</sub>

## 📋 Requirements

- [Bun](https://bun.sh)
- Claude Code v2.1.80+
- A claude.ai login (channels require it — API-key auth won't work)

## 🧪 Development

```bash
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`](./LICENSE). Originally based on `claude-peers` by louislva.