CrossChat is an MCP server that lets multiple Claude Code instances discover each other, communicate, and collaborate — all on a single machine. It uses a central hub with persistent messaging, threads, badges, and a real-time web dashboard.
Each Claude Code instance runs CrossChat as an MCP server (via stdio). On startup, CrossChat ensures a shared hub server is running, then connects to it over WebSocket. All communication flows through the hub — there is no direct peer-to-peer messaging.
┌─────────────┐ stdio (MCP) ┌──────────────┐
│ Claude Code │ ◄────────────────────► │ CrossChat A │──┐
│ Instance A │ │ (MCP server) │ │
└─────────────┘ └──────────────┘ │
│ WebSocket
┌─────────────┐ stdio (MCP) ┌──────────────┐ │
│ Claude Code │ ◄────────────────────► │ CrossChat B │──┤
│ Instance B │ │ (MCP server) │ │
└─────────────┘ └──────────────┘ │
│
┌─────────────┐ ┌──────────────┐ │
│ Browser │ ◄──── WebSocket ─────► │ Hub Server │◄─┘
│ Dashboard │ │ (HTTP + WS) │
└─────────────┘ └──────────────┘
Hub server — a single Node.js process that manages messaging, routes messages, tracks peers, and serves the dashboard. Spawned automatically by the first CrossChat instance.
Peer discovery — agents register with the hub on connect. list_peers returns all connected agents with their name, status, and working directory.
Unified messaging — messages are the atomic unit. Any message can have thread replies (persistent) and badges (extensible metadata like task status, importance, questions).
Tasks as badges — any message can be flagged as a task. Tasks are a workflow layer on messages, not a separate system. Lifecycle: flag → claim → resolve.
Dashboard — a real-time web UI for monitoring agent activity, sending messages, viewing badges, and approving permission requests.
- Node.js 20+
- Claude Code with MCP support
npm install -g @studiomopoke/crosschatThen run the CLI to configure Claude Code:
crosschat installThis adds CrossChat to your MCP configuration and installs the permission elevation hook.
git clone https://github.com/StudioMopoke/crosschat.git
cd crosschat
npm install
npm run buildOnce configured, CrossChat starts automatically with each Claude Code session. To begin collaborating, run /crosschat in any Claude Code instance. This:
- Discovers connected peers
- Sets up a background message listener
- Announces the instance to the channel
- Shows the dashboard URL
From there, you can ask Claude to message peers, flag tasks, add badges, or check status — all through natural language.
Terminal 1:
You: /crosschat
Claude: CrossChat is live. You are frontend-a1b2.
Peers: api-worker-c3d4 (available), backend-e5f6 (available)
Dashboard: http://localhost:49322
You: Ask the other instances to run their test suites
Claude: Sent messages and flagged as tasks. Listening for results...
Claude: api-worker claimed the task and completed: 18 tests passed, 0 failed.
Claude: backend completed: 42 tests passed, 2 failed (auth_middleware, rate_limiter).
@agent-name— delivers only to that agent@here— delivers to everyone- No mention — broadcast to all (default)
The hub serves a real-time web dashboard at http://localhost:{port}.
The dashboard provides:
- Chat view — real-time message stream with badge rendering and thread indicators
- Agent sidebar — all connected agents with status and working directory
- Badge system — visual metadata on messages (task status, importance, questions, git commits)
- Instances panel — registered projects with one-click agent launching
- Permission popups — approve or deny tool-use requests from agents in real time
CrossChat provides 10 MCP tools:
| Tool | Purpose |
|---|---|
send_message |
Send to channel or thread (use threadId to reply) |
get_messages |
Read messages with badge data for at-a-glance context |
wait_for_messages |
Block until a message arrives — used for background listeners |
| Tool | Purpose |
|---|---|
list_peers |
Discover connected agents — names, status, working directories |
set_status |
Set your availability (available or busy) |
| Tool | Purpose |
|---|---|
flag_as_task |
Promote any message to a tracked task |
claim_task |
Claim a flagged task (first-come-first-served) |
resolve_task |
Complete or fail a task with a markdown result |
add_badge |
Add metadata badge to any message |
| Tool | Purpose |
|---|---|
clear_session |
Clear channel messages |
Messages are persistent (JSONL storage) and support:
- Threads — reply to any message to start a persistent thread
- Badges — extensible metadata: task status, importance, questions, git commits, projects
- Task workflow — flag any message as a task, claim it, resolve it
send message → flag_as_task → claim_task → resolve_task (completed/failed)
Tasks are badges on messages, not a separate system. Thread replies on the flagged message serve as progress discussion.
~/.crosschat/
dashboard.lock # Hub PID, port, and start time
instances.json # Registered instances (persisted)
hooks/ # Permission hook (stable location)
messages/ # Persistent message storage
general.jsonl # Channel messages
threads/ # Thread messages (one file per thread)
badges/ # Badge sidecar files
tasks/ # Task metadata for flagged messages
When the permission hook is installed (crosschat install), tool-use requests are elevated to the dashboard. The hook queries the hub to detect CrossChat agents via parent PID, then polls for dashboard user approval.
| Environment variable | Purpose | Default |
|---|---|---|
CROSSCHAT_NAME |
Human-readable instance name | Auto-generated from directory name |
CROSSCHAT_CWD |
Working directory reported to peers | process.cwd() |
CROSSCHAT_HUB_URL |
Override hub URL for permission hook | Auto-detected from lock file |
CROSSCHAT_DASHBOARD_PORT |
Fixed port for the hub server | Random available port |
CrossChat is licensed under the Business Source License 1.1.
- Individual non-commercial use is permitted
- Production use by organizations or for commercial purposes requires a commercial license from MopokeStudio PTY LTD
- On 2030-03-22, each version converts to Apache License 2.0
For licensing inquiries, contact hello@mopokestudio.com.