# claude-peers: letting several Claude Code sessions talk to each other > A small MCP server and a localhost broker daemon that let running Claude Code instances discover one another and exchange messages. The interesting parts are the one-second polling fallback, the channel push path, and a permission flag the README's own alias quietly drops. **louislva/claude-peers-mcp** — Allow all your Claude Codes to message each other ad-hoc! - Repository: https://github.com/louislva/claude-peers-mcp - Stars: 2,208 · Forks: 307 - Language: TypeScript - License: MIT - Published: 2026-10-08 · Updated: 2026-10-08 · Language: en - Canonical page: https://hysenlabs.com/projects/louislva-claude-peers-mcp ## What a second Claude Code session is missing The README's opening line is the problem statement: let your Claude Code instances find each other and talk, and when you are running 5 sessions across different projects, any Claude can discover the others and send messages that arrive instantly. Each of those sessions is otherwise isolated. A session in one repository cannot see what a session in another is doing, cannot ask it a question, and cannot hand off a finding. The usual workaround is the human in the middle, copying text between windows. This project's whole contribution is to put a broker between the sessions so that coordination is a tool call rather than a copy and paste. The scope is deliberately narrow. There are four tools and the README lists all of them in a table: `list_peers` finds other Claude Code instances, scoped to `machine`, `directory`, or `repo`; `send_message` sends a message to another instance by ID; `set_summary` describes what the current instance is working on; and `check_messages` manually checks for messages as a fallback if you are not using channel mode. The scoping options on `list_peers` are the detail that makes this usable. A message bus that can only see every session on the machine is noise, while one that can be limited to the current directory or the current git repository is something you would actually leave enabled. ## A broker daemon on port 7899 with SQLite behind it The architecture is short enough to describe in one paragraph, and the README does exactly that. A broker daemon runs on `localhost:7899` with a SQLite database. Each Claude Code session spawns an MCP server that registers with the broker and polls for messages every second. Inbound messages are pushed into the session through the claude channel protocol, so Claude sees them immediately. So there are two delivery mechanisms and they are not the same thing. Channel push is the fast path and the reason the README can say messages arrive instantly. Polling every second is the fallback, and it is also what `check_messages` exposes as a manual tool. If you have ever had a session silently not receive something, that gap between the two paths is where it would happen, which is why the fallback tool is documented at all. Three operational details come with the broker. It auto-launches when the first session starts, so there is no separate daemon to remember to start. It cleans up dead peers automatically, which handles the common case of closing a terminal without a clean shutdown. And everything is localhost-only, with no remote discovery and no network exposure in the default configuration. The repository tree is consistent with a small TypeScript program rather than a framework: `broker.ts`, `server.ts`, `cli.ts`, `index.ts`, a `shared/` directory, plus `CLAUDE.md` and `.mcp.json`. The `package.json` shows three scripts, `bun broker.ts`, `bun server.ts` and `bun test`, and a single runtime dependency on `@modelcontextprotocol/sdk`. ## Installing from a clone rather than a package There is no `npm install claude-peers` step, because there is nothing to install from a registry. The quick start is a clone, an install and a registration: ```bash git clone https://github.com/louislva/claude-peers-mcp.git ~/claude-peers-mcp # or wherever you like cd ~/claude-peers-mcp bun install ``` Then the MCP server is registered at user scope, which is what makes claude-peers available in every Claude Code session from any directory: ```bash claude mcp add --scope user --transport stdio claude-peers -- bun ~/claude-peers-mcp/server.ts ``` The `--transport stdio` detail is the one that matters if you have registered MCP servers before, because the server is a TypeScript file executed by Bun rather than a compiled binary on your PATH. That is also why the README asks you to replace `~/claude-peers-mcp` with wherever you cloned it, and why moving or deleting that directory breaks every session at once rather than one of them. `package.json` makes the no-registry decision explicit: the package name is `claude-peers`, the version is `0.1.0`, and the field `"private": true` is set. Meanwhile `package.json` also declares `"license": "MIT"` and the repository has a `LICENSE` file. Both facts are current. The project is MIT licensed in the sense that you may read and adapt the code, and it is deliberately unpublished in the sense that there is no version you can pin with a version range. Anyone adopting this is tracking a git checkout. ## The channel flag, and the alias that drops a permission flag Step three of the quick start runs Claude Code with two flags: ```bash claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers ``` The first flag is a permission decision and the second is the feature gate that exposes the channel protocol the README relies on for instant delivery. The README then suggests an alias: ```bash alias claudepeers='claude --dangerously-load-development-channels server:claude-peers' ``` Put those two side by side and they are not the same command. The alias drops `--dangerously-skip-permissions`. That is arguably an improvement in safety, since the quick start disables permission prompts for the whole session, and it is also a change in behaviour, because whatever your workflow expected to run without approval will now prompt. Either is defensible, but the README does not say that the alias differs, so a reader who copies the alias has quietly adopted different permission behaviour than the documented quick start. The requirements list adds the version floor that makes this fragile in a second way: Bun, Claude Code v2.1.80+, and a claude.ai login, with the README stating plainly that channels require a login and that API key authentication will not work. So this does not run against a headless API setup, and it depends on a development flag rather than a stable public interface. ## Summaries, the CLI, and the three environment variables Peers are more useful with context attached, so each instance publishes a one-line summary that others see in `list_peers`. The README describes two paths for setting it. If `OPENAI_API_KEY` is present in the environment, the instance generates a brief summary on startup using `gpt-5.4-nano`, at what it describes as fractions of a cent, based on the directory, git branch and recent files. Without the API key, Claude sets its own summary through the `set_summary` tool. The first path is worth thinking about before you enable it. It sends your working directory name, current branch and recently touched file paths to an OpenAI model on every session startup, which is a reasonable thing for a local tool but is not a decision the tool makes for you. The README does present it as opt-in by virtue of the environment variable being absent by default, and it does not document a way to change the model. There is also a command line path for the same data, useful when you want to see the fleet without opening a session: ```bash cd ~/claude-peers-mcp bun cli.ts status # broker status + all peers bun cli.ts peers # list peers bun cli.ts send # send a message into a Claude session bun cli.ts kill-broker # stop the broker ``` Configuration is three environment variables: `CLAUDE_PEERS_PORT` defaulting to `7899`, `CLAUDE_PEERS_DB` defaulting to `~/.claude-peers.db`, and `OPENAI_API_KEY`, which has no default. Two of them are worth changing if you run more than one checkout at a time, since a second clone with the same defaults will either fail to bind the port or write to the same database. ## Maintenance state and the case against building on it The repository is not archived and the last push was on 2026-04-26. There are no GitHub releases at all, so there is no version history to consult when something breaks and no changelog explaining a behaviour change. The version in `package.json` is `0.1.0`, which has not moved across that history. That combination, a single pushed date with no releases and a pre-1.0 version, is a reasonable description of a personal tool that works on the author's machine. It is not a reason to avoid it if your problem is exactly the problem it solves, because the whole thing is four TypeScript files plus a shared directory and is easy to read in an afternoon. It is a reason not to make it load-bearing. The design constraint worth naming is that this project does not implement messaging. It implements peer discovery and a message channel, and it delegates delivery to the claude channel protocol, which is why it needs `--dangerously-load-development-channels`, a specific Claude Code version, and a claude.ai login. If your setup uses API key authentication, or you want a general-purpose bridge from a Claude session to a chat service, this is the wrong tool, because the interesting half of that problem is somebody else's and is not in this repository. Within the narrower goal of letting co-located Claude Code sessions find each other, the design is coherent and the failure modes are visible: a broker that must be running, a one-second polling floor when channel push is unavailable, and a `kill-broker` command for when it is not. ## Conclusion claude-peers solves a narrow, real problem: you have several Claude Code sessions open on different projects and want them to coordinate without you relaying every message by hand. It is a local development tool with no release history, a version pinned at 0.1.0 in `package.json`, and a dependency on a Claude Code development flag plus a claude.ai login, so it is not something to build a team workflow on. What to verify first is the permission story: the quick start launches Claude Code with `--dangerously-skip-permissions` while the suggested alias omits that flag, and those two commands are not equivalent. Read the four tool names, then check whether `claude --dangerously-load-development-channels` still exists in your Claude Code version before wiring anything into a script. ## FAQ ### How do I install claude-peers MCP? Clone the repository, run `bun install` inside it, then register the server at user scope with `claude mcp add --scope user --transport stdio claude-peers -- bun ~/claude-peers-mcp/server.ts`. There is no published npm package; the server is run directly from `server.ts` using Bun. ### How does claude-peers deliver messages instantly? Through the claude channel protocol, which requires launching Claude Code with `--dangerously-load-development-channels`. When channel mode is not in use, each session's MCP server polls the broker every second and `check_messages` is available as a manual fallback. ### Does claude-peers need an OpenAI API key? Only for auto-summary. If `OPENAI_API_KEY` is set, each instance generates a startup summary using `gpt-5.4-nano` from the directory, git branch and recent files. Without it, Claude sets its own summary through the `set_summary` tool. ### What are the requirements for running claude-peers? Bun, Claude Code v2.1.80 or newer, and a claude.ai login. The README states that channels require the login and that API key authentication will not work. ### Can claude-peers be installed from npm? No. `package.json` sets `"private": true` with version `0.1.0` and the name `claude-peers`, so nothing is published to a registry even though the project is MIT licensed. Installation means tracking a git checkout and updating it with git. ### How do I change the claude-peers broker port or database? Set `CLAUDE_PEERS_PORT`, which defaults to `7899`, or `CLAUDE_PEERS_DB`, which defaults to `~/.claude-peers.db`. These matter if you run more than one checkout, since two brokers on one port or one database file will conflict. ## Sources - [Issues](https://github.com/louislva/claude-peers-mcp/issues) - [License: MIT](https://github.com/louislva/claude-peers-mcp/blob/main/LICENSE) - [louislva/claude-peers-mcp on GitHub](https://github.com/louislva/claude-peers-mcp) - [README](https://github.com/louislva/claude-peers-mcp/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/louislva-claude-peers-mcp