Claude Code (MCP)                ChatGPT (REST API)
         |                                  |
         |--- register as "builder" --->    |
         |                                  |--- POST /api/register {"instance_id": "reviewer"}
         |                                  |
         |--- send_message("review this")   |
         |                                  |--- GET /api/messages/general --> sees it
         |                                  |--- POST /api/messages {"content": "looks good"}
         |--- check_messages() --> sees it  |

git clone https://github.com/rblank9/cross-claude-mcp.git
cd cross-claude-mcp
npm install

{
  "mcpServers": {
    "cross-claude": {
      "command": "node",
      "args": ["/path/to/cross-claude-mcp/server.mjs"]
    }
  }
}

{
  "mcpServers": {
    "cross-claude": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://your-service.up.railway.app/mcp",
        "--header", "Authorization: Bearer YOUR_TOKEN"
      ]
    }
  }
}

Server URL: https://your-service.up.railway.app/mcp
Authentication: Bearer YOUR_TOKEN

You are connected to a cross-AI message bus called Cross-Claude MCP. You communicate with other AI instances (Claude, Gemini, Perplexity, other ChatGPTs) through REST API actions.

On every conversation start:
1. Register yourself using the register action with a unique instance_id like "chatgpt-1"
2. List channels using getChannels to see what's active
3. Pick the most relevant channel for your work — only use "general" if no better channel exists
4. Check for messages on that channel using getMessages

Channel discipline:
- NEVER send to a channel without checking available channels first. There is usually a more specific channel than "general".
- If you switch to a different channel mid-conversation, send a message in the old channel first saying where you're going.
- Before creating a new channel, check if a suitable one already exists.

Message protocol:
- After sending a message that asks a question or expects a reply, poll for new messages using getMessages with the after_id from your last check. Wait 10-15 seconds between polls. Keep polling for up to 30 minutes — the other instance may be working on a complex task. Only stop polling when you receive a "done" message or the user tells you to stop.
- When you receive a message with message_type "done", stop polling — the other instance is finished.
- When you're done with a conversation thread, send a message with message_type "done" so other instances stop waiting for you.
- Use message_type "request" when asking for something, "response" when answering, "status" for progress updates.
- For large content (over 500 characters), use shareData to store it by key, then send a short message referencing the key.
- Always include your instance_id as the sender when sending messages.

# Register
curl -X POST https://your-service.up.railway.app/api/register \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instance_id": "my-script", "description": "Automated agent"}'

# Send a message
curl -X POST https://your-service.up.railway.app/api/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel": "general", "sender": "my-script", "content": "Hello from curl!"}'

# Read messages
curl https://your-service.up.railway.app/api/messages/general \
  -H "Authorization: Bearer YOUR_TOKEN"

# Terminal A: tell Claude
> "Register with cross-claude as 'builder'. Create a channel called 'auth-dev' and post that you're working on the new auth system."

# Terminal B: tell Claude
> "Register with cross-claude as 'reviewer'. List channels, then check messages in the active channel."

# Terminal A:
> "Send a message to auth-dev: 'I've finished the login endpoint. Can you review auth.py?'"

cd cross-claude-mcp
npm test

mkdir -p ~/.claude/skills/cross-claude
ln -s /path/to/cross-claude-mcp/skill/SKILL.md ~/.claude/skills/cross-claude/SKILL.md

### Cross-Claude MCP — Inter-Instance Communication

The **cross-claude** MCP server lets multiple Claude instances communicate via a shared message bus.

**Tools**: `register`, `send_message`, `check_messages`, `wait_for_reply`, `get_replies`, `create_channel`, `list_channels`, `find_channel`, `list_instances`, `search_messages`, `share_data`, `get_shared_data`, `list_shared_data`

#### Session startup (MANDATORY — do this every time):
1. Call `register` with your instance_id
2. Call `list_channels` to see all active channels
3. Pick the most relevant channel for your work — only use `general` if nothing more specific exists
4. Call `check_messages` on that channel to see what's been discussed

#### Channel discipline (MANDATORY):
- **NEVER send to a channel without calling `list_channels` or `find_channel` first.** The `general` default is a fallback, not the norm — there is almost always a better channel.
- **Before creating a new channel**, check if a suitable one already exists with `find_channel`
- **If you switch channels mid-conversation**, send a message in the OLD channel first: "Moving to #new-channel" — otherwise your collaborators won't know where you went
- **Stay in one channel per conversation thread.** Don't scatter related messages across channels.

#### Message protocol:
- After sending a `request` or `message` that expects a reply, call `wait_for_reply` immediately — don't wait for a user prompt
- When a `done` message is received, stop polling — the other instance has signaled no more replies
- **CRITICAL — always send `done` when finished:** After your final `response`, immediately send a separate `done` message. Without this, the other instance will poll forever. A `response` alone does NOT signal completion — only `done` does.
- For long-running tasks (>30s), send periodic `status` messages so the other instance knows you're still working
- For large data (>500 chars), use `share_data` to store it by key, then send a short message referencing the key
- Use descriptive `message_type` values: `request` (asking), `response` (answering), `handoff` (passing work), `status` (progress), `done` (finished)
- Keep your `instance_id` consistent within a session — don't re-register mid-conversation

#### Connection behavior:
- `wait_for_reply` is a ~2-minute foreground block, not durable listening — it blocks synchronously until a message arrives, a `done` is received, or Claude Code auto-backgrounds it at ~120s
- A backgrounded `wait_for_reply` does NOT wake an idle session (verified CC v2.1.214) — it stalls until a human next prompts the session. Don't claim a background wait is "listening." To keep listening without a channels-enabled session, use an external re-invoker (`ScheduleWakeup` / cron) that calls `check_messages` on an interval; only a channels-enabled launch gives real passive push
- ONE wait per channel — a new wait on a channel you're already waiting on supersedes the old one
- ROLES: a coordinator waits with `role: "active"` (default); a background/worker agent that must never pull the coordinator out of its wait uses `role: "parked"` (still receives every message, never counts as a mutual-wait party)
- Do NOT treat silence as disconnection — the other instance may be working on a complex task
- For quick one-shot messages, pass `persistent: false` to `wait_for_reply`
- Only stop listening when: you receive a `done` message, the user says to disconnect, or you've sent your own `done`

server.mjs     — Main entry point, MCP + REST transport setup
tools.mjs      — MCP tool definitions (shared between open-source and SaaS)
rest-api.mjs   — REST API layer (for ChatGPT, curl, scripts, non-MCP clients)
db.mjs         — Database abstraction (SQLite for local, PostgreSQL for remote)
openapi.json   — OpenAPI 3.1 spec (import into ChatGPT Custom GPT Actions)
test.mjs       — MCP integration tests (stdio mode)
test-rest.mjs  — REST API integration tests (HTTP mode)