{
  "markdown": "# peer-channel\n\nLets multiple Claude Code sessions talk to each other locally.\n\n![peer-channel in action](docs/peer-channel-in-action.png)\n\n## Architecture\n\n```\n CC session A                CC session B\n      |                           |\n      | stdio (MCP)               | stdio (MCP)\n      v                           v\n  peer-channel               peer-channel\n (~/.peer-channel/          (~/.peer-channel/\n   sessions/A.sock)           sessions/B.sock)\n      |           peer-to-peer            |\n      +------- AF_UNIX + NDJSON ----------+\n```\n\nEach session's channel subprocess claims a name by acquiring a lockfile at `~/.peer-channel/sessions/<name>.lock` and binds a Unix domain socket at `~/.peer-channel/sessions/<name>.sock`. Messaging is direct peer-to-peer: the sender opens a one-shot connection to the recipient's socket, writes one NDJSON JSON-RPC request, reads the response, closes.\n\nNo central daemon. No Docker. No open TCP port.\n\n## Requirements\n\n- Node.js 20+\n- Claude Code v2.1.80+ with claude.ai login (channels are in research preview)\n- On Team/Enterprise plans, an admin must enable channels\n- Linux or macOS (Windows support is not yet wired up)\n\n## Install\n\nFrom within Claude Code:\n\n```\n/plugin marketplace add rophy/claude-peer-channel\n/plugin install peer-channel@rophy-plugins\n```\n\n(To run from a local checkout for development, see [CONTRIBUTING.md](CONTRIBUTING.md).)\n\n## Usage\n\nLaunch any Claude Code session with the channel enabled:\n\n```bash\nclaude --dangerously-load-development-channels plugin:peer-channel@rophy-plugins\n```\n\nThe `--dangerously-load-development-channels` flag is required during the channels research preview until peer-channel is on the approved allowlist.\n\nOn startup, the channel reports its registered name to stderr:\n\n```\n[peer-channel] registered as: my-project\n```\n\n### Tools exposed to Claude\n\n- **`list_sessions`** — returns the names of all other sessions currently reachable.\n- **`send_message(to, message, in_reply_to?)`** — sends a message to another session. Pass `in_reply_to` with a prior message's id to thread replies.\n\n### Inbound messages\n\nMessages from peer sessions arrive in the receiving Claude's context as:\n\n```\n<channel source=\"plugin:peer-channel:peer-channel\" from=\"peer-name\" message_id=\"uuid\" in_reply_to=\"optional-uuid\">\nmessage body\n</channel>\n```\n\n### Session naming\n\nBy default, a session's name is `basename(cwd)`. If that name is already claimed by another live session, the channel appends a short random suffix.\n\nOverride with the `PEER_CHANNEL_SESSION_NAME` environment variable:\n\n```bash\nPEER_CHANNEL_SESSION_NAME=backend-api claude --dangerously-load-development-channels plugin:peer-channel@rophy-plugins\n```\n\n### Host-Level Peers\n\nBy default, sessions are only visible to other sessions running as the same OS user. To make a session discoverable by all local users (e.g. for a shared service), enable host-level mode:\n\n**Via environment variable:**\n```bash\nPEER_CHANNEL_HOST_LEVEL=true claude --dangerously-load-development-channels plugin:peer-channel@rophy-plugins\n```\n\n**Via project `.env` file:**\n```\nPEER_CHANNEL_HOST_LEVEL=true\n```\n\nThe runtime env var takes precedence over `.env`.\n\nHost-level sessions register under `/run/peer-channel/{username}/` and are named `{username}/{session-name}`. Other sessions discover them automatically — no configuration needed on the discovery side.\n\n#### Setup (one-time, as root)\n\n```bash\n# Create the shared directory\nsudo tee /etc/tmpfiles.d/peer-channel.conf <<< 'd /run/peer-channel 1777 root root -'\nsudo systemd-tmpfiles --create\n```\n\n#### Host-level session naming\n\nHost-level peers always include the OS username prefix:\n- `expose-web/default` — user `expose-web`, session `default`\n- `cat/myproject` — user `cat`, session `myproject`\n\nHost-level sessions are singleton — if another instance with the same name is already running, the new one fails to start.\n\n## Reference\n\n### Protocol\n\nNewline-delimited JSON-RPC 2.0 over an AF_UNIX stream socket. One request per connection.\n\n| Method | Params | Result |\n|---|---|---|\n| `ping` | `{}` | `{name, version, protocol}` |\n| `deliver` | `{from, message, in_reply_to?}` | `{message_id}` |\n\nError codes follow JSON-RPC conventions (`-32700` parse, `-32600` invalid request, `-32601` method not found, `-32602` invalid params, `-32603` internal).\n\n### Filesystem layout\n\n```\n~/.peer-channel/                    # user-level (default)\n└── sessions/\n    ├── alice.lock/    # directory, created by proper-lockfile\n    ├── alice.sock     # AF_UNIX socket\n    ├── bob.lock/\n    └── bob.sock\n\n/run/peer-channel/                  # host-level (opt-in)\n├── expose-web/\n│   ├── default.lock/\n│   └── default.sock\n└── cat/\n    ├── myproject.lock/\n    └── myproject.sock\n```\n\n## Design decisions\n\n- **No offline delivery.** If the target session isn't reachable, `send_message` returns an error.\n- **No presence push.** Sessions don't receive join/leave events; call `list_sessions` on demand.\n- **Per-user trust.** The sessions directory is `mode 0700` and sockets are `mode 0600` — only the user that owns the home directory can interact with the channel.\n- **Peer messages are untrusted input.** Another session's text is treated as a user-like request, not as instructions to Claude.\n- **Name claim via [`proper-lockfile`](https://www.npmjs.com/package/proper-lockfile).** Stale locks are auto-reclaimed after 10s; the owner refreshes every 5s while alive. A crashed session becomes reclaimable within that window.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for the trust model and known attack surface.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for local development setup, build commands, and running the plugin from a source checkout.\n\n## License\n\nMIT\n",
  "bytes": 5765,
  "sha": "5ab0e182f471c187b50383387b3be40fa6a74e39c6a6d65f9bb6818d998b92b4",
  "repo_slug": "rophy/claude-peer-channel",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_rophy_claude_peer_channel_peer_channel_a9236c25/readme"
}