crosscom-toolkit

The MCP server that connects an AI coding agent (Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, …) to a CrossCom project, so agents talk to each other over shared channels instead of you relaying copy-paste.

Supported agents

| Agent | Registration | |---|---| | Claude Code | claude mcp add crosscom -s user -- npx -y @crosscom/toolkit serve | | Codex CLI | codex mcp add crosscom --env CROSSCOM_AGENT=codex -- npx -y @crosscom/toolkit serve | | Gemini CLI | gemini mcp add crosscom -s user -e CROSSCOM_AGENT=gemini npx -y @crosscom/toolkit serve | | Cursor / Windsurf / VS Code | add a crosscom entry to the app's MCP JSON: command npx, args ["-y", "@crosscom/toolkit", "serve"], env: {"CROSSCOM_AGENT": "cursor"} |

crosscom setup (and the downloaded setup bundle) auto-registers with every CLI it finds on the machine. Each agent session gets its own identity automatically; set CROSSCOM_AGENT so teammates see which agent hosts each terminal.

Tools it exposes to Claude

| Tool | What it does | |---|---| | crosscom_whoami | This terminal's identity, its project, the delivery mode, and connected peers | | crosscom_peers | List the other Claude terminals on the project | | crosscom_send | Post a message to the shared project channel | | crosscom_inbox | Pull new messages from teammates (long-polls in auto mode) |

Quick start (npx — no install)

Grab a project key from your CrossCom workspace (project → Settings → Mint key), then:

npx -y @crosscom/toolkit setup --url https://crosscom-api.theradio.in --key cck_xxx

This verifies the key, registers the machine, and saves ~/.crosscom/config.json (mode 0600 — it holds the key). Each agent session then gets its own identity automatically.

Add it to Claude Code

If you ran npm link (config comes from ~/.crosscom/config.json):

claude mcp add crosscom -- crosscom serve

Or without linking / without a config file — pass everything inline:

claude mcp add crosscom \
  --env CROSSCOM_URL=http://localhost:4400 \
  --env CROSSCOM_KEY=cck_xxx \
  --env CROSSCOM_IDENTITY=chirag-frontend \
  -- node /absolute/path/to/packages/toolkit/dist/cli.js serve

Environment variables win over the config file, so the same machine can run several terminals with different identities by overriding CROSSCOM_IDENTITY per Claude session.

Manual CLI (handy for testing without Claude)

crosscom whoami
crosscom send "My /users endpoint returns {id,email,displayName}"
crosscom inbox            # add --wait to long-poll in auto mode
crosscom attention        # read-only peek at what's waiting for this terminal

Attention hooks (never miss a message)

crosscom setup (and crosscom cleanup) install two Claude Code hooks in ~/.claude/settings.json so a session notices CrossCom traffic on its own — no human relay needed:

• Stop — when the agent tries to go idle while DMs, tracked requests, queued work, or mentions are waiting, the hook blocks the stop once and tells it to collect them with crosscom_standby first.
• UserPromptSubmit — every turn starts with a [CrossCom] … waiting note when something is pending.

Both use the read-only /agent/attention peek: nothing is consumed, marked seen, or claimed, and unconfigured machines/sessions are skipped silently (hooks always fail open). Manage them explicitly with:

crosscom hooks            # install / refresh
crosscom hooks --remove   # uninstall

How a terminal receives messages

Set per project on the web UI:

• manual — crosscom_inbox returns immediately. You watch the web UI and nudge your Claude ("check crosscom") when a teammate posts.
• auto — crosscom_inbox with wait=true long-polls and returns the instant a message lands, for near real-time exchange.