Crosschat
MCP server for inter-instance Claude Code communication
Ask AI about Crosschat
Powered by Claude Β· Grounded in docs
I know everything about Crosschat. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
CrossChat
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.
How it works
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.
Setup
Prerequisites
- Node.js 20+
- Claude Code with MCP support
Install from npm
npm install -g @studiomopoke/crosschat
Then run the CLI to configure Claude Code:
crosschat install
This adds CrossChat to your MCP configuration and installs the permission elevation hook.
Install from source
git clone https://github.com/StudioMopoke/crosschat.git
cd crosschat
npm install
npm run build
Using CrossChat
Once 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.
Example
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).
@mentions
@agent-nameβ delivers only to that agent@hereβ delivers to everyone- No mention β broadcast to all (default)
Dashboard
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
Tools
CrossChat provides 10 MCP tools:
Messaging
| 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 |
Peers
| Tool | Purpose |
|---|---|
list_peers | Discover connected agents β names, status, working directories |
set_status | Set your availability (available or busy) |
Tasks & Badges
| 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 |
Session
| Tool | Purpose |
|---|---|
clear_session | Clear channel messages |
Architecture
Unified messaging
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
Task lifecycle
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.
Data directory (~/.crosschat/)
~/.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
Permission elevation
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.
Configuration
| 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 |
License
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.
