{"id":50335131,"url":"https://github.com/monkfromearth/intermind","last_synced_at":"2026-05-29T13:01:15.631Z","repository":{"id":356734891,"uuid":"1233301406","full_name":"monkfromearth/intermind","owner":"monkfromearth","description":"An MCP server that lets Claude Code, Codex, Cursor, Cline, Windsurf, and any other MCP-speaking coding agent hold threaded conversations with each other.","archived":false,"fork":false,"pushed_at":"2026-05-09T12:49:31.000Z","size":252,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T14:44:00.667Z","etag":null,"topics":["a2a","agent","ai","bun","llm","mcp","mcp-client","mcp-server"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/intermind","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/monkfromearth.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-08T20:11:05.000Z","updated_at":"2026-05-09T12:48:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/monkfromearth/intermind","commit_stats":null,"previous_names":["monkfromearth/intermind"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/monkfromearth/intermind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkfromearth%2Fintermind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkfromearth%2Fintermind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkfromearth%2Fintermind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkfromearth%2Fintermind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/monkfromearth","download_url":"https://codeload.github.com/monkfromearth/intermind/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkfromearth%2Fintermind/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33652986,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a","agent","ai","bun","llm","mcp","mcp-client","mcp-server"],"created_at":"2026-05-29T13:01:14.688Z","updated_at":"2026-05-29T13:01:15.620Z","avatar_url":"https://github.com/monkfromearth.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/monkfromearth/intermind/main/docs/logos/intermind-typography-white.png\"\u003e\n    \u003cimg alt=\"Intermind\" src=\"https://raw.githubusercontent.com/monkfromearth/intermind/main/docs/logos/intermind-typography-black.png\" width=\"320\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003eby \u003ca href=\"https://monkfrom.earth\"\u003e\u003cstrong\u003emonkfromearth\u003c/strong\u003e\u003c/a\u003e\u003c/sub\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003ePair programming for AI coding agents.\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  An \u003ca href=\"https://modelcontextprotocol.io\"\u003eMCP\u003c/a\u003e server that lets \u003cstrong\u003eClaude Code, Codex, Cursor, Cline, Windsurf\u003c/strong\u003e, and any other MCP-speaking coding agent \u003cstrong\u003ehold threaded conversations with each other\u003c/strong\u003e.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/monkfromearth/intermind/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://github.com/monkfromearth/intermind/workflows/CI/badge.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"#install\"\u003e\u003cimg alt=\"Bun ≥ 1.1\" src=\"https://img.shields.io/badge/bun-%E2%89%A5%201.1-black?logo=bun\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://modelcontextprotocol.io\"\u003e\u003cimg alt=\"MCP 2025-11-25\" src=\"https://img.shields.io/badge/MCP-2025--11--25-blue\"\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg alt=\"MIT License\" src=\"https://img.shields.io/badge/license-MIT-green\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick start\u003c/a\u003e ·\n  \u003ca href=\"#wire-it-into-your-coding-agent\"\u003eWire-up\u003c/a\u003e ·\n  \u003ca href=\"#your-first-conversation\"\u003eFirst conversation\u003c/a\u003e ·\n  \u003ca href=\"./docs/guides/tools.md\"\u003eTool reference\u003c/a\u003e ·\n  \u003ca href=\"./docs/guides/examples.md\"\u003eExamples\u003c/a\u003e ·\n  \u003ca href=\"./docs/guides/troubleshooting.md\"\u003eTroubleshooting\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Why this exists\n\nClaude 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.\n\nThat's Intermind. It does *one* thing — move messages between agents — and gets out of the way.\n\n\u003e **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.\n\n## What you get\n\n- 💬 **Direct messages and broadcasts** between any agent in your room\n- 🧵 **Threaded conversations** so a back-and-forth review stays grouped\n- 📥 **Inbox** for catching up on pending messages\n- ⏳ **Long-poll wait** so an agent can block until its peer replies\n- 🚪 **Rooms** so two pairs working on different features stay isolated — agents pick the room from the current git branch automatically\n- 🔒 **Bearer-token auth** so agents can't impersonate each other\n\nSix tools, a thread model, rooms. That's the whole product.\n\n## Architecture in one picture\n\n```\n        ┌──────────────────┐         ┌──────────────────┐\n        │   Claude Code    │         │     Codex CLI    │\n        │   (MCP client)   │         │   (MCP client)   │\n        └────────┬─────────┘         └─────────┬────────┘\n                 │ stdio                       │ stdio\n                 ▼                             ▼\n       ┌──────────────────┐         ┌──────────────────┐\n       │ Intermind subproc│         │ Intermind subproc│\n       │   (MCP server)   │         │   (MCP server)   │\n       └────────┬─────────┘         └─────────┬────────┘\n                │                             │\n                └──────────────┬──────────────┘\n                               ▼\n                    ┌────────────────────┐\n                    │  Room \"feature-x\"  │\n                    │  Room \"feature-y\"  │\n                    │  Room \"main\"       │\n                    └────────────────────┘\n```\n\nEach 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.\n\n## Quick start\n\nOne-click install for the supported clients:\n\n\u003cp\u003e\n  \u003ca href=\"cursor://anysphere.cursor-deeplink/mcp/install?name=intermind\u0026config=eyJjb21tYW5kIjoiYnVueCIsImFyZ3MiOlsiLXkiLCJpbnRlcm1pbmQiXX0=\"\u003e\n    \u003cimg alt=\"Add to Cursor\" src=\"https://img.shields.io/badge/Add%20to-Cursor-000000?style=for-the-badge\u0026logo=cursor\u0026logoColor=white\"\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\n  \u003ca href=\"vscode:mcp/install?%7B%22name%22%3A%22intermind%22%2C%22command%22%3A%22bunx%22%2C%22args%22%3A%5B%22-y%22%2C%22intermind%22%5D%7D\"\u003e\n    \u003cimg alt=\"Install in VS Code\" src=\"https://img.shields.io/badge/Install%20in-VS%20Code-007ACC?style=for-the-badge\u0026logo=visualstudiocode\u0026logoColor=white\"\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\n  \u003ca href=\"vscode-insiders:mcp/install?%7B%22name%22%3A%22intermind%22%2C%22command%22%3A%22bunx%22%2C%22args%22%3A%5B%22-y%22%2C%22intermind%22%5D%7D\"\u003e\n    \u003cimg alt=\"Install in VS Code Insiders\" src=\"https://img.shields.io/badge/Install%20in-VS%20Code%20Insiders-1D9D74?style=for-the-badge\u0026logo=visualstudiocode\u0026logoColor=white\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nOr one command for Claude Code:\n\n```bash\nclaude mcp add --scope project intermind -- bunx -y intermind\n```\n\nRestart 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.\n\nFor 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).\n\nYou need [Bun](https://bun.com) ≥ 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.\n\n## Install\n\nThe 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.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eInstall globally from npm\u003c/b\u003e — `intermind` on your \u003ccode\u003e$PATH\u003c/code\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n```bash\nbun install -g intermind\n```\n\nNow every wire-up snippet works with `command: \"intermind\"` instead of `command: \"bunx\"`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eInstall globally from GitHub\u003c/b\u003e — same as above, pre-npm\u003c/summary\u003e\n\u003cbr\u003e\n\n```bash\nbun install -g github:monkfromearth/intermind\n```\n\nUse this if you want to track `main` instead of the latest npm release.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDownload a prebuilt binary\u003c/b\u003e — no Bun required at runtime\u003c/summary\u003e\n\u003cbr\u003e\n\nEach tagged release ships single-file binaries for macOS and Linux. Grab yours from the [latest release](https://github.com/monkfromearth/intermind/releases/latest), make it executable, drop it on your `$PATH`:\n\n```bash\n# macOS arm64\ncurl -L -o intermind https://github.com/monkfromearth/intermind/releases/latest/download/intermind-darwin-arm64\nchmod +x intermind\nsudo mv intermind /usr/local/bin/intermind\n```\n\nAvailable: `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.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClone the repo\u003c/b\u003e — only if you want to hack on Intermind\u003c/summary\u003e\n\u003cbr\u003e\n\n```bash\ngit clone https://github.com/monkfromearth/intermind.git\ncd intermind\nbun install\n```\n\nIn 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.\n\n\u003c/details\u003e\n\n## Wire it into your coding agent\n\nThe shape is the same for every client: launch `bunx -y intermind` over stdio. Pick yours below.\n\n\u003e **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\"`.\n\n### Claude Code\n\nProject-scoped (commits `.mcp.json` so the whole team picks it up):\n\n```bash\nclaude mcp add --scope project intermind -- bunx -y intermind\n```\n\nOr user-scoped (just you, every project):\n\n```bash\nclaude mcp add --scope user intermind -- bunx -y intermind\n```\n\nRestart Claude Code, then `claude mcp list` to verify.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCodex CLI\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nEdit `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`):\n\n```toml\n[mcp_servers.intermind]\ncommand = \"bunx\"\nargs = [\"-y\", \"intermind\"]\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nCreate `.cursor/mcp.json` at your project root (or `~/.cursor/mcp.json` for global):\n\n```json\n{\n  \"mcpServers\": {\n    \"intermind\": {\n      \"command\": \"bunx\",\n      \"args\": [\"-y\", \"intermind\"]\n    }\n  }\n}\n```\n\nVerify in **Settings → Features → MCP**.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWindsurf (Codeium)\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nEdit `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"intermind\": {\n      \"command\": \"bunx\",\n      \"args\": [\"-y\", \"intermind\"]\n    }\n  }\n}\n```\n\nThen in Windsurf: **Cascade panel → MCP servers → Refresh**.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eVS Code (GitHub Copilot agent mode)\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nCreate `.vscode/mcp.json` in your workspace:\n\n```json\n{\n  \"servers\": {\n    \"intermind\": {\n      \"type\": \"stdio\",\n      \"command\": \"bunx\",\n      \"args\": [\"-y\", \"intermind\"]\n    }\n  }\n}\n```\n\nOpen Copilot Chat, switch to **Agent** mode — the tools become available.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCline (VS Code extension)\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nOpen Cline's MCP settings (Cline icon → ⚙ → Edit MCP Settings):\n\n```json\n{\n  \"mcpServers\": {\n    \"intermind\": {\n      \"command\": \"bunx\",\n      \"args\": [\"-y\", \"intermind\"]\n    }\n  }\n}\n```\n\nCline reloads when you save.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eZed\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nIn `~/.config/zed/settings.json`:\n\n```json\n{\n  \"context_servers\": {\n    \"intermind\": {\n      \"command\": {\n        \"path\": \"bunx\",\n        \"args\": [\"-y\", \"intermind\"]\n      }\n    }\n  }\n}\n```\n\nRestart Zed.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eContinue.dev\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nIn `~/.continue/config.json`:\n\n```json\n{\n  \"experimental\": {\n    \"modelContextProtocolServers\": [\n      {\n        \"transport\": {\n          \"type\": \"stdio\",\n          \"command\": \"bunx\",\n          \"args\": [\"-y\", \"intermind\"]\n        }\n      }\n    ]\n  }\n}\n```\n\nContinue picks up changes without a restart.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Desktop\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nEdit `claude_desktop_config.json` (`~/Library/Application Support/Claude/` on macOS, `%APPDATA%\\Claude\\` on Windows, `~/.config/Claude/` on Linux):\n\n```json\n{\n  \"mcpServers\": {\n    \"intermind\": {\n      \"command\": \"bunx\",\n      \"args\": [\"-y\", \"intermind\"]\n    }\n  }\n}\n```\n\nQuit and re-launch Claude Desktop after saving.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAny other MCP client\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n```\ncommand:    bunx\nargs:       [\"-y\", \"intermind\"]\ntransport:  stdio\n```\n\nFor per-client notes (verify steps, restart behaviour, gotchas), see [`docs/guides/clients.md`](./docs/guides/clients.md).\n\n\u003c/details\u003e\n\n### Verify it's wired up\n\nAfter 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.\n\n## Your first conversation\n\nA 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.\n\n**Step 1 — In `~/projects/api`** (a Claude Code session on `feature-checkout`):\n\n\u003e *\"Hop on Intermind as the backend dev — see who else is around.\"*\n\nThe 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.\"*\n\n**Step 2 — In `~/projects/web`** (a Codex session on the same branch, `feature-checkout`):\n\n\u003e *\"Hop on Intermind as the frontend and say hi to the backend.\"*\n\nSame trick — Codex reads its branch, joins `feature-checkout`, calls `peers`, finds the backend agent, fires a `send` introducing itself.\n\n**Step 3 — Back in the backend session:**\n\n\u003e *\"Anything new on Intermind?\"*\n\nClaude 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.\n\n**What the agent does for you on `join`:**\n\n| You don't pass | Agent picks |\n| --- | --- |\n| `room` | The current git branch (`git branch --show-current`). Outside a git repo, `\"main\"`. |\n| Anything else | Nothing — the agent prompts you for `display_name` and `role` if it doesn't already know them. |\n\nThe 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\"`.\n\n## Teach your agent how to use Intermind\n\nCoding 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.\n\n**The block lives in one file:** [`docs/agent-system-prompt.md`](./docs/agent-system-prompt.md).\n\n**Recommended install — `@`-include the raw URL** so updates land automatically:\n\n```\n@https://raw.githubusercontent.com/monkfromearth/intermind/main/docs/agent-system-prompt.md\n```\n\nPaste 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:\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code\u003c/b\u003e — \u003ccode\u003eCLAUDE.md\u003c/code\u003e or Skill\u003c/summary\u003e\n\u003cbr\u003e\n\nProject-scoped (commits to the repo, picked up by the whole team):\n\n```\nCLAUDE.md\n```\n\nUser-scoped (every project, just you):\n\n```\n~/.claude/CLAUDE.md\n```\n\nAs a Claude Skill (loaded on demand):\n\n```\n~/.claude/skills/intermind/SKILL.md\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCodex CLI\u003c/b\u003e — \u003ccode\u003eAGENTS.md\u003c/code\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nUser-scoped:\n\n```\n~/.codex/AGENTS.md\n```\n\nProject-scoped:\n\n```\n.codex/AGENTS.md\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor\u003c/b\u003e — \u003ccode\u003e.cursor/rules/intermind.mdc\u003c/code\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n```\n.cursor/rules/intermind.mdc\n```\n\nOr the legacy single-file form:\n\n```\n.cursorrules\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCline\u003c/b\u003e — \u003ccode\u003eAGENTS.md\u003c/code\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n```\nAGENTS.md\n```\n\n(in the project root)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWindsurf\u003c/b\u003e — global rules\u003c/summary\u003e\n\u003cbr\u003e\n\n```\n~/.codeium/windsurf/memories/global_rules.md\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eContinue.dev\u003c/b\u003e — \u003ccode\u003econfig.json\u003c/code\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nEdit `~/.continue/config.json` and set the block as the value of `systemMessage`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eZed\u003c/b\u003e — \u003ccode\u003esettings.json\u003c/code\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nEdit `~/.config/zed/settings.json` and add the block to the assistant configuration.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAny other agent\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nDrop 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.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWant stronger guarantees? Hooks and mid-turn delivery\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nThe 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:\n\n- **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.\n- **Claude Code mid-turn (`Monitor` + `intermind watch`).** The agent spawns `intermind watch --token \u003ctok\u003e` 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).\n- **Hooks (Claude Code \u0026 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).\n\nNo 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).\n\n\u003c/details\u003e\n\n## Tools\n\nThe full surface — six tools, no resources, no prompts.\n\n| Tool | Purpose | Returns |\n| --- | --- | --- |\n| `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? }` |\n| `whoami` | Confirm your identity from the session token. | `{ agent_id, display_name, role, connected_at }` |\n| `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 }] }` |\n| `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? }` |\n| `inbox` | Pull pending (unread) messages addressed to you. Marks them read by default. | `{ messages, count }` |\n| `listen` | Long-poll for the next unread message on a thread. Blocks up to `timeout_sec` (default 25s, max 120). | `{ message, timeout }` |\n\nFor the full reference — every parameter, return shape, error condition, and example — see [`docs/guides/tools.md`](./docs/guides/tools.md).\n\nEvery 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.\n\n## A real conversation under the hood\n\nWhat the JSON-RPC actually looks like when Claude asks Codex to review a patch.\n\n**1. Both agents join the same room.** Each picks the room from its current git branch — both repos are on `feature-checkout`.\n\n```text\nclaude  → join { display_name: \"Claude\",  role: \"implementer\", room: \"feature-checkout\" }\n        ← { agent_id: \"agt_a1b2…\", token: \"tok_…\", room: \"feature-checkout\", room_size: 0 }\n\ncodex   → join { display_name: \"Codex\",   role: \"reviewer\",    room: \"feature-checkout\" }\n        ← { agent_id: \"agt_c3d4…\", token: \"tok_…\", room: \"feature-checkout\", room_size: 1 }\n```\n\n**2. Claude finds Codex and sends the patch.**\n\n```text\nclaude  → peers { token: \"tok_…\" }\n        ← { room: \"feature-checkout\", agents: [{ id: \"agt_c3d4…\", display_name: \"Codex\", … }] }\n\nclaude  → send { token: \"tok_…\", to: \"agt_c3d4…\", body: \"please review:\\n```diff\\n…\\n```\" }\n        ← { thread_id: \"thr_e5f6…\", delivered: [\"agt_c3d4…\"], message_ids: […] }\n```\n\n**3. Codex was long-polling for work — the message is already there.**\n\n```text\ncodex   → listen { token: \"tok_…\", thread_id: \"thr_e5f6…\", timeout_sec: 60 }\n        ← { message: { body: \"please review …\", from_agent: \"agt_a1b2…\" }, timeout: false }\n```\n\n**4. Codex reads, thinks, replies on the same thread.**\n\n```text\ncodex   → send {\n            token:     \"tok_…\",\n            to:        \"agt_a1b2…\",\n            thread_id: \"thr_e5f6…\",\n            body:      \"line 42 should use unwrap_or; counter-patch:\\n```diff\\n…\\n```\"\n          }\n```\n\n**5. Claude was already long-polling; the reply lands immediately.**\n\n```text\nclaude  → listen { token: \"tok_…\", thread_id: \"thr_e5f6…\", timeout_sec: 60 }\n        ← { message: { body: \"line 42 should …\", from_agent: \"agt_c3d4…\" }, timeout: false }\n```\n\nThat's the whole loop. No special tools for diffs, reviews, or tasks — just messages on a thread.\n\n## Use cases\n\nReal workflows people actually run, with the prompt you give the agent. The full prompt-by-prompt walkthroughs (with the JSON each tool call sends) live in [`docs/guides/examples.md`](./docs/guides/examples.md).\n\n| Use case | What happens | When to reach for it |\n| --- | --- | --- |\n| **Review loop** | Implementer sends a patch, reviewer replies with line-level fixes on the same thread, repeat until both agree. | Two agents, same feature, one writes and one critiques. The classic pair-programming dance. |\n| **Backend ↔ frontend on a feature** | Backend agent on the API repo and frontend agent on the web repo join the same room (auto-picked from the branch name) and trade contracts: *\"new endpoint shape is X\"*, *\"got it, here's how I'm calling it\"*. | Two agents in two repos working on one user-visible change. |\n| **Async coordination** | Implementer keeps coding while the reviewer reads in another window. Both `inbox` at the start of every turn instead of blocking on `listen`. | When you don't want one agent stuck waiting on the other. |\n| **Hand-off** | Agent A wraps a chunk of work, posts a status message on a hand-off thread; agent B was long-polling on that thread, picks up where A left off. | Long-running tasks where the user wants to swap who's driving. |\n| **Broadcast** | One agent fires `send({ to: \"*\", … })` — every other agent in the room gets it. | *\"I'm refactoring `parser/`, heads up if you're touching it.\"* |\n| **Parallel threads** | Same two agents hold multiple conversations at once, isolated by `thread_id` — one for the parser bug, one for the migration. | When the same pair is juggling more than one topic. |\n| **Catching up after a crash** | Your MCP client crashed mid-session. The new session calls `peers` to find its old `agent_id`, then `inbox` with `mark_read: false` to peek at the history. | Recovery — sessions are ephemeral, messages are persisted. |\n\n## Troubleshooting\n\nThe three most common issues:\n\n| Symptom | Likely cause |\n| --- | --- |\n| **Agent doesn't see the tools** | Forgot to restart the agent after editing config; or `intermind` isn't on `$PATH`. Run `which intermind` to check. |\n| **Two agents can't see each other** | They joined different room names. Each agent picks its room from the current git branch — if one agent ran outside a git repo it landed in `\"main\"` instead. Ask both agents what room they're in (rule 3 of the [system prompt](./docs/agent-system-prompt.md) makes them announce it on `join`) and re-`join` the laggard with the right name. |\n| **`listen` always times out** | Your peer replied without `thread_id` (so it started a new thread), or they aren't actually working. Fall back to `inbox`. |\n\nFor the full troubleshooting guide and how to get help, see [`docs/troubleshooting.md`](./docs/guides/troubleshooting.md).\n\n## Documentation\n\nThe [`docs/`](./docs/) folder splits into **guides** (how to use Intermind) and a **knowledge base** (why it's built this way).\n\n**Guides** — how to use Intermind:\n\n- [Tool reference](./docs/guides/tools.md) — every parameter, return shape, error, and example.\n- [Wire-up cookbook](./docs/guides/clients.md) — copy-paste configs for every major MCP client.\n- [Examples](./docs/guides/examples.md) — review loop, async coordination, broadcast, hand-off, hook setup.\n- [Worktrees \u0026 per-feature rooms](./docs/guides/worktrees.md) — when one feature spans BE and FE in two repos.\n- [Troubleshooting \u0026 support](./docs/guides/troubleshooting.md) — common issues, inspection one-liners, where to ask for help.\n\n**Knowledge base** — why Intermind looks this way:\n\n1. [MCP primer](./docs/knowledge-base/01-mcp-primer.md) — what the protocol actually is, in 5 minutes.\n2. [Coding-agent MCP clients](./docs/knowledge-base/02-coding-agent-mcp-clients.md) — how Claude Code and Codex use MCP.\n3. [Transports](./docs/knowledge-base/03-transports.md) — stdio vs Streamable HTTP.\n4. [Why Intermind](./docs/knowledge-base/04-why-intermind.md) — the gap in MCP that this fills.\n5. [Coordination model](./docs/knowledge-base/05-coordination-model.md) — the mailbox, threads, broadcasts.\n6. [Prior art](./docs/knowledge-base/06-prior-art.md) — Agent-MCP, A2A, and how we relate.\n7. [Glossary](./docs/knowledge-base/07-glossary.md) — quick reference for every term.\n\n## Non-goals\n\nSaying no is half the design. Intermind will not do any of these:\n\n- ❌ Tasks, todos, or workflow orchestration. Each agent already has its own task tracking.\n- ❌ A shared key/value or document store. If agents want shared notes, they post to a thread.\n- ❌ First-class diff/review/PR types. Diffs are text inside messages.\n- ❌ Editing the user's working tree. Receiving agents apply diffs with their own Edit tool.\n- ❌ A2A protocol bridging. (Complementary protocol; not in scope.)\n- ❌ A web dashboard or hosted observer.\n- ❌ Hosting or running the agents themselves.\n\nIf you want any of those, see [`CONTRIBUTING.md`](./CONTRIBUTING.md) and [`ROADMAP.md`](./ROADMAP.md) for what's on the table and what isn't.\n\n## FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDoes this work over the network?\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nNo. 0.0.3 is stdio-only and assumes local trust (same machine, same user) — it covers \"two agents on my laptop\" but stops there. Cross-machine support via Streamable HTTP is in [`ROADMAP.md`](./ROADMAP.md) under \"later\" — no schedule.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eHow is this different from Agent2Agent (A2A)?\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nA2A is a peer-to-peer protocol between agents. Intermind is an MCP server — every agent connects through MCP, the protocol they already speak. No new protocol surface for the agents to learn. See [`docs/knowledge-base/06-prior-art.md`](./docs/knowledge-base/06-prior-art.md).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWhat happens if two agents write at the same time?\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nSQLite WAL mode allows concurrent reads and serialises writes. The message volume here — text messages between two or three agents — is far below SQLite's single-writer limits.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCan I run more than one room?\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nYes — pass a different `room` value to `join`. One pair of agents in `room: \"feature-auth\"`, another in `room: \"feature-billing\"`, and they're invisible to each other. The agent defaults to the current git branch name (per the [system prompt](./docs/agent-system-prompt.md)), so per-feature isolation is usually automatic — you don't have to think about it.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCan I run agents on different machines?\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nNot today. 0.0.3 covers everything on one laptop; cross-machine support via Streamable HTTP is in [`ROADMAP.md`](./ROADMAP.md) under \"later\" — no schedule.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eHow does a peer's message reach me \u003cem\u003eduring\u003c/em\u003e a turn instead of waiting for my next `inbox` call?\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nShort answer: today, on Claude Code only, via the `Monitor` tool plus a one-line subcommand `intermind watch --token \u003cyour_token\u003e`. The system-prompt block tells the agent to spawn that watcher once at session start; it tails the SQLite file and prints one JSON line per new message addressed to you. Claude Code's `Monitor` surfaces each line as a notification in the agent's context, mid-turn. The agent reads it, replies on the same `thread_id`, and goes back to whatever it was doing.\n\nOn every other client (Cursor, Cline, Windsurf, Continue, Zed, Codex), the floor is `listen` (long-poll, blocks the turn) plus `inbox` at turn start. That's not as snappy as mid-turn delivery, but it's universal.\n\nThe protocol-correct answer — server-push over MCP — doesn't have a delivery path to the agent's context on any client today (elicitation is a server-to-user dialog, not a server-to-agent-context channel). It's on the roadmap; the day a client routes arbitrary server notifications to the agent, we drop the watch subprocess. Full reasoning: [`docs/decisions/0001-message-delivery.md`](./docs/decisions/0001-message-delivery.md).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eHow do I know an agent is \"online\"?\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nCheck `last_seen` on the agent row — it bumps on every authenticated tool call. There's no presence ping; if an agent hasn't called anything in a while, you can't tell whether it's thinking or gone.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eIs the message body inspected?\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nNo. Intermind moves bytes. Whatever you put in `body` arrives at the recipient unchanged. Diffs, JSON, prose — all just text.\n\n\u003c/details\u003e\n\n## Contributing\n\nPRs welcome. Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) first — Intermind is small on purpose, so there's a high bar for \"more code.\" If your idea is a new tool, open an issue before sending a PR.\n\n## License\n\n[MIT](./LICENSE) © 2026 [monkfromearth](https://monkfrom.earth).\n\n---\n\n\u003cp align=\"center\"\u003eBuilt by \u003ca href=\"https://monkfrom.earth\"\u003emonkfromearth\u003c/a\u003e.\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonkfromearth%2Fintermind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonkfromearth%2Fintermind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonkfromearth%2Fintermind/lists"}