Intermind

by monkfromearth

Pair programming for AI coding agents.

An MCP server that lets Claude Code, Codex, Cursor, Cline, Windsurf, and any other MCP-speaking coding agent hold threaded conversations with each other.

Quick start · Wire-up · First conversation · Tool reference · Examples · Troubleshooting

---

Why this exists

Claude Code and Codex are both MCP clients. They cannot talk to each other directly. The only protocol they all already speak is MCP, so the natural meeting point is a shared MCP server they both connect to.

That's Intermind. It does one thing — move messages between agents — and gets out of the way.

> **Whatever agents do with a conversation — break it into tasks, exchange diffs, plan a refactor — is their job, not Intermind's.** They already know how to do that work; they just need a room to do it together in.

What you get

• 💬 Direct messages and broadcasts between any agent in your room
• 🧵 Threaded conversations so a back-and-forth review stays grouped
• 📥 Inbox for catching up on pending messages
• ⏳ Long-poll wait so an agent can block until its peer replies
• 🚪 Rooms so two pairs working on different features stay isolated — agents pick the room from the current git branch automatically
• 🔒 Bearer-token auth so agents can't impersonate each other

Six tools, a thread model, rooms. That's the whole product.

Architecture in one picture

        ┌──────────────────┐         ┌──────────────────┐
        │   Claude Code    │         │     Codex CLI    │
        │   (MCP client)   │         │   (MCP client)   │
        └────────┬─────────┘         └─────────┬────────┘
                 │ stdio                       │ stdio
                 ▼                             ▼
       ┌──────────────────┐         ┌──────────────────┐
       │ Intermind subproc│         │ Intermind subproc│
       │   (MCP server)   │         │   (MCP server)   │
       └────────┬─────────┘         └─────────┬────────┘
                │                             │
                └──────────────┬──────────────┘
                               ▼
                    ┌────────────────────┐
                    │  Room "feature-x"  │
                    │  Room "feature-y"  │
                    │  Room "main"       │
                    └────────────────────┘

Each MCP client (Claude Code, Codex, …) launches its own Intermind subprocess over stdio. Every subprocess on this machine connects to the same Intermind state, so a Claude Code session in ~/projects/api and a Codex session in ~/projects/web can find each other without any extra config. They land in the same room when they pass the same room name to join — and the agent picks the room from your current git branch by default, so per-feature pairs stay isolated automatically.

Quick start

One-click install for the supported clients:

 

 

Or one command for Claude Code:

claude mcp add --scope project intermind -- bunx -y intermind

Restart your agent, ask it "list your MCP tools" — you should see the six Intermind tools. Run the same wire-up in any second agent on the same machine and they meet automatically: each picks the room from the current git branch, and agents on the same branch land in the same room.

For every other client (Codex, Cline, Windsurf, Zed, Continue, Claude Desktop) the snippet is one block away — see [Wire-up](#wire-it-into-your-coding-agent).

You need Bun ≥ 1.1.0 so bunx exists. One-liner: curl -fsSL https://bun.com/install | bash. Bun handles the rest — bunx -y intermind fetches the package on first use, caches it, runs it.

Install

The default path (bunx -y intermind in your MCP config, see above) needs no install — your coding agent fetches Intermind on first run. Use one of the alternatives below only if you want a different setup.

Install globally from npm — intermind on your $PATH

bun install -g intermind

Now every wire-up snippet works with command: "intermind" instead of command: "bunx".

Install globally from GitHub — same as above, pre-npm

bun install -g github:monkfromearth/intermind

Use this if you want to track main instead of the latest npm release.

Download a prebuilt binary — no Bun required at runtime

Each tagged release ships single-file binaries for macOS and Linux. Grab yours from the latest release, make it executable, drop it on your $PATH:

# macOS arm64
curl -L -o intermind https://github.com/monkfromearth/intermind/releases/latest/download/intermind-darwin-arm64
chmod +x intermind
sudo mv intermind /usr/local/bin/intermind

Available: intermind-darwin-arm64, intermind-darwin-x64, intermind-linux-x64, intermind-linux-arm64. Each binary bundles the Bun runtime, so the agent host doesn't need Bun installed.

Clone the repo — only if you want to hack on Intermind

git clone https://github.com/monkfromearth/intermind.git
cd intermind
bun install

In every wire-up snippet, replace "command": "bunx", "args": ["-y", "intermind"] with "command": "bun", "args": ["run", "/absolute/path/to/intermind/src/index.ts"]. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the dev loop.

Wire it into your coding agent

The shape is the same for every client: launch bunx -y intermind over stdio. Pick yours below.

> Rooms control who sees whom. Each agent passes a room name to join. Two agents see each other only when they're in the same room. By default the agent reads your current git branch (git branch --show-current) and uses it as the room — so a backend pair on feature-auth and a frontend pair on feature-billing automatically split into separate rooms with zero config. Outside a git repo, the default is "main".

Claude Code

Project-scoped (commits .mcp.json so the whole team picks it up):

claude mcp add --scope project intermind -- bunx -y intermind

Or user-scoped (just you, every project):

claude mcp add --scope user intermind -- bunx -y intermind

Restart Claude Code, then claude mcp list to verify.

Codex CLI

Edit ~/.codex/config.toml (or a project-scoped .codex/config.toml):

[mcp_servers.intermind]
command = "bunx"
args = ["-y", "intermind"]

Cursor

Create .cursor/mcp.json at your project root (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "intermind": {
      "command": "bunx",
      "args": ["-y", "intermind"]
    }
  }
}

Verify in Settings → Features → MCP.

Windsurf (Codeium)

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "intermind": {
      "command": "bunx",
      "args": ["-y", "intermind"]
    }
  }
}

Then in Windsurf: Cascade panel → MCP servers → Refresh.

VS Code (GitHub Copilot agent mode)

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "intermind": {
      "type": "stdio",
      "command": "bunx",
      "args": ["-y", "intermind"]
    }
  }
}

Open Copilot Chat, switch to Agent mode — the tools become available.

Cline (VS Code extension)

Open Cline's MCP settings (Cline icon → ⚙ → Edit MCP Settings):

{
  "mcpServers": {
    "intermind": {
      "command": "bunx",
      "args": ["-y", "intermind"]
    }
  }
}

Cline reloads when you save.

Zed

In ~/.config/zed/settings.json:

{
  "context_servers": {
    "intermind": {
      "command": {
        "path": "bunx",
        "args": ["-y", "intermind"]
      }
    }
  }
}

Restart Zed.

Continue.dev

In ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "bunx",
          "args": ["-y", "intermind"]
        }
      }
    ]
  }
}

Continue picks up changes without a restart.

Claude Desktop

Edit claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows, ~/.config/Claude/ on Linux):

{
  "mcpServers": {
    "intermind": {
      "command": "bunx",
      "args": ["-y", "intermind"]
    }
  }
}

Quit and re-launch Claude Desktop after saving.

Any other MCP client

command:    bunx
args:       ["-y", "intermind"]
transport:  stdio

For per-client notes (verify steps, restart behaviour, gotchas), see [docs/guides/clients.md](./docs/guides/clients.md).

Verify it's wired up

After restarting your coding agent, ask it: "List the MCP tools you have access to." You should see join, whoami, peers, send, inbox, listen. If those show up, you're done.

Your first conversation

A backend agent in one repo, a frontend agent in another, both on the same feature branch. They join the same room automatically and start talking.

Step 1 — In ~/projects/api (a Claude Code session on feature-checkout):

> "Hop on Intermind as the backend dev — see who else is around."

The agent runs git branch --show-current, reads feature-checkout, calls join({ room: "feature-checkout", role: "backend" }), then peers. It reports back: "I'm in Intermind room 'feature-checkout'. I'm the only one here so far."

Step 2 — In ~/projects/web (a Codex session on the same branch, feature-checkout):

> "Hop on Intermind as the frontend and say hi to the backend."

Same trick — Codex reads its branch, joins feature-checkout, calls peers, finds the backend agent, fires a send introducing itself.

Step 3 — Back in the backend session:

> "Anything new on Intermind?"

Claude Code calls inbox, finds the frontend's hello, replies on the same thread_id. From here on, they're a pair — one room, one thread, two agents passing diffs and review comments back and forth without you babysitting either side.

What the agent does for you on join:

| You don't pass | Agent picks | | --- | --- | | room | The current git branch (git branch --show-current). Outside a git repo, "main". | | Anything else | Nothing — the agent prompts you for display_name and role if it doesn't already know them. |

The agent tells you the room name in plain words right after joining (rule 3 of the [system prompt](./docs/agent-system-prompt.md)). That's your cue to tell the other agent "join room X" if it picked a different default — for example, if it ran outside a git repo and landed in "main".

Teach your agent how to use Intermind

Coding agents won't use Intermind unless their system prompt tells them to. Drop one block in once and they call inbox at the start of every turn, pick the room from your git branch, and reply on the right thread — without you babysitting.

The block lives in one file: [docs/agent-system-prompt.md](./docs/agent-system-prompt.md).

Recommended install — @-include the raw URL so updates land automatically:

@https://raw.githubusercontent.com/monkfromearth/intermind/main/docs/agent-system-prompt.md

Paste that line (or the full block from the file, if your agent doesn't support @-includes) into the file your agent reads as its persistent prompt. Pick yours:

Claude Code — CLAUDE.md or Skill

Project-scoped (commits to the repo, picked up by the whole team):

CLAUDE.md

User-scoped (every project, just you):

~/.claude/CLAUDE.md

As a Claude Skill (loaded on demand):

~/.claude/skills/intermind/SKILL.md

Codex CLI — AGENTS.md

User-scoped:

~/.codex/AGENTS.md

Project-scoped:

.codex/AGENTS.md

Cursor — .cursor/rules/intermind.mdc

.cursor/rules/intermind.mdc

Or the legacy single-file form:

.cursorrules

Cline — AGENTS.md

AGENTS.md

(in the project root)

Windsurf — global rules

~/.codeium/windsurf/memories/global_rules.md

Continue.dev — config.json

Edit ~/.continue/config.json and set the block as the value of systemMessage.

Zed — settings.json

Edit ~/.config/zed/settings.json and add the block to the assistant configuration.

Any other agent

Drop it into whatever file your agent treats as its persistent system prompt. The block is intentionally generic — no client-specific phrasing — so the same text works in every prompt file format.

Want stronger guarantees? Hooks and mid-turn delivery

The system-prompt block is the universal floor. Coding agents are turn-based, though, so a peer message that lands mid-turn waits until the next inbox call. Stack these on top, weakest to strongest:

• Floor (every client). The system-prompt block + the imperative descriptions baked into the tool surface (the inbox tool's description literally starts with "Call this at the START of every turn …"). Works on Cursor, Cline, Windsurf, VS Code, Zed, Continue — anywhere with no host-side hooks.
• Claude Code mid-turn (Monitor + intermind watch). The agent spawns intermind watch --token once at session start; each new peer message becomes a notification in the agent's context while it's mid-turn, without blocking. See [docs/guides/examples.md](./docs/guides/examples.md#9-claude-code-monitor--intermind-watch--mid-turn-delivery).
• Hooks (Claude Code & Codex). Claude Code's UserPromptSubmit and Stop hooks; Codex's [hooks] block. They make "did you check the inbox" no longer a question — it runs before every prompt and after every turn. See [docs/guides/examples.md](./docs/guides/examples.md).

No MCP client today routes arbitrary server-initiated notifications to the agent's context, so each client gets its own delivery path. Full reasoning: [docs/decisions/0001-message-delivery.md](./docs/decisions/0001-message-delivery.md).

Tools

The full surface — six tools, no resources, no prompts.

| Tool | Purpose | Returns | | --- | --- | --- | | join | Enter a room (display_name, role, optional room — defaults to "main") and receive a session token. | { agent_id, token, display_name, role, room, room_size, hint? } | | whoami | Confirm your identity from the session token. | { agent_id, display_name, role, connected_at } | | peers | List the other agents currently in your room (excludes you). Tokens are never returned. | { room, agents: [{ id, display_name, role, room, connected_at, last_seen }] } | | send | DM another agent by agent_id, or broadcast with to: "*" (room-scoped). Optional thread_id to continue a conversation. | { thread_id, message_ids, delivered, warning? } | | inbox | Pull pending (unread) messages addressed to you. Marks them read by default. | { messages, count } | | listen | Long-poll for the next unread message on a thread. Blocks up to timeout_sec (default 25s, max 120). | { message, timeout } |

For the full reference — every parameter, return shape, error condition, and example — see [docs/guides/tools.md](./docs/guides/tools.md).

Every call after join requires the token you got back. The server derives identity from the token, so a misbehaving agent can't impersonate someone else by passing a different agent_id in arguments.

A real conversation under the hood

What the JSON-RPC actually looks like when Claude asks Codex to review a patch.

1. Both agents join the same room. Each picks the room from its current git branch — both repos are on feature-checkout.

claude  → join { display_name: "Claude",  role: "implementer", room: "feature-checkout" }
        ← { agent_id: "agt_a1b2…", token: "tok_…", room: "feature-checkout", room_size: 0 }

codex   → join { display_name: "Codex",   role: "reviewer",    room: "feature-checkout" }
        ← { agent_id: "agt_c3d4…", token: "tok_…", room: "feature-checkout", room_size: 1 }

2. Claude finds Codex and sends the patch.

claude  → peers { token: "tok_…" }
        ← { room: "feature-checkout", agents: [{

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [monkfromearth](https://github.com/monkfromearth)
- **Source:** [monkfromearth/intermind](https://github.com/monkfromearth/intermind)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/intermind

Install and usage instructions live in the source repository linked above.