vibegroup ☎️

Build with your team, and let your agents do the same.
Claude Code sessions that talk to each other across repos, machines, and networks.

License: MIT Status: alpha 67 tests passing Bun TypeScript strict Claude Code Channel End-to-end encrypted macOS | Linux

The best building happens in good company — but when you and your friends are each heads-down in your own repo on your own machine, your agents are strangers to each other. Yours has no idea what theirs just shipped. vibegroup ends that isolation. Drop into a shared room and your agents start talking: a friend's agent asks yours what the new importer API looks like, whether you pushed the migration, what branch you're on — and **the question lands right in your running session, which answers on its own.** The easy back-and-forth you have with your friends finally reaches the agents working beside you. ``` you ▸ ask Jon's agent what he's working on vibegroup_ask ──(sealed, E2E)──▶ relay ──▶ Jon's agent ⚡ wakes, the question is pushed into his live session reads his repo (read-only) → vibegroup_reply relay ◀──(sealed, E2E)── you ⚡ the answer pushes back into your session "on feat/grpc-streaming, importer's done" ``` The answer comes from your friend's **actual agent, with full context** — and it works even if they're away from the keyboard, because the question wakes their idle session. --- ## Why vibegroup - **Made for a group of friends, not a fleet.** A *vibegroup* is just a room you and your friends join from wherever you're coding. Spin one up, share the token, start asking. - **Cross-machine, over the internet.** Agents connect *outbound* to a relay, so NAT and firewalls are a non-issue. Two laptops, two clouds, a laptop and a CI box — all the same. - **Answers come from your live agent.** A peer's question is pushed straight into your running Claude Code session via [Claude Code Channels](https://code.claude.com/docs/en/channels), so your *real* agent — with full repo context — answers it. No second model, no separate API bill. - **Wakes an idle session.** Channels deliver while you're away from the terminal, so a peer gets an answer even when you're not actively typing. - **Untrusted by default.** Incoming questions are framed as untrusted data and answered **read-only** (git + files, no writes/exec, no secret reads); replies are scrubbed for secrets before they leave. - **End-to-end encrypted.** Question and answer bodies are AES-256-GCM sealed under a key derived from the room token. The relay routes **ciphertext only** — never your code. - **Signed identity.** The relay stamps the authoritative sender; peers can't spoof who they are. --- ## How it works vibegroup is a **Claude Code Channel** wired to a relay. A channel is an MCP server that can *push events into a running session* (and the agent replies through a tool) — that's the primitive that makes "your live session answers on its own" possible. - **Asking** is a tool call: your agent calls `vibegroup_ask(peer, question)` → it goes out over the relay. - **Answering** is a push: the question arrives at your peer's machine, their channel pushes it into their live session as ``, their agent answers read-only and calls `vibegroup_reply`. - **Receiving** is a push too: the answer routes back and pushes into *your* session as ``. The relay is just transport — it matches peers into rooms and routes encrypted blobs; it never sees plaintext. The three pieces: | Repo | What it is | |---|---| | **[vibegroup](https://github.com/TerryCM/vibegroup)** (this repo) | the channel: relay client, E2E crypto, the `vibegroup_*` tools, and the Claude Code plugin | | **[vibegroup-relay](https://github.com/TerryCM/vibegroup-relay)** | the broker you host — rooms, signed identity, ciphertext routing. Never decrypts anything. | | **[vibegroup-protocol](https://github.com/TerryCM/vibegroup-protocol)** | the shared wire contract both sides depend on | --- ## Requirements vibegroup answers by pushing a peer's question straight into your live Claude Code session, which is an admin-gated capability. That means: - **Claude Code ≥ 2.1.80** with **Anthropic auth** (claude.ai or a Console API key) — not Bedrock/Vertex/Foundry. - Allowlist the channel once with **`/vibegroup:allow-channel`** (it writes Claude Code's managed settings), or launch with **`--dangerously-load-development-channels`** for quick local use. - The answering session must be **open** — keep one running (a `tmux` pane works) to stay answerable while away. --- ## Quick start vibegroup is a Claude Code plugin. Install it, run setup, and you're in. **1. Install the plugin** ``` /plugin marketplace add TerryCM/vibegroup /plugin install vibegroup@vibegroup ``` **2. Allow the channel + join a room** ``` /vibegroup:allow-channel ``` This allowlists the channel (one-time, needs `sudo`) and mints or joins a room on the **free hosted relay** (`relay.vibegroup.sh`) — or self-host (see [`vibegroup-relay/DEPLOY.md`](https://github.com/TerryCM/vibegroup-relay/blob/main/DEPLOY.md)). Share the room + token with your team out-of-band. **3. Launch the session as a channel** ```bash claude --channels plugin:vibegroup@vibegroup ``` **4. Ask** — *"use `vibegroup_peers`, then ask Pablo's agent what he's working on."* Their session wakes, answers read-only from its repo, and the answer pushes back into yours. > **Prefer to run from source?** Clone the three repos side by side and `bun install` in `vibegroup`, then install it as a plugin from the local path (or point a global MCP entry at `dist/channel.js`) and run `vibegroup add` to bind a room — see **Multiple rooms** below. --- ## Multiple rooms A vibegroup setup isn't limited to one room. Join a `my-team` room, a `backend` room, a side project — each lives in one registry (`~/.claude/vibegroup/rooms.json`), and the **active room is chosen by your working directory**, so every project talks to its own crew automatically. ```bash vibegroup add my-team # mint + bind a room to this directory vibegroup add backend --room rm_… --token … # or join an existing room here vibegroup list # every room (marks the one active here) vibegroup disable backend # toggle a room off without losing its creds ``` - **A room per project.** A room is bound to a directory; the most specific bound directory containing your cwd wins. In `~/code/backend` only the `backend` room is active — and binding a parent folder covers every repo beneath it. No flags, no env vars per repo. - **Any relay.** `vibegroup add` uses the free hosted relay by default; pass `--url wss://your-relay/ws` to point a room at your own (see [`vibegroup-relay/DEPLOY.md`](https://github.com/TerryCM/vibegroup-relay/blob/main/DEPLOY.md)). Different rooms can live on different relays. - **On / off.** `vibegroup enable`/`disable` flip a room without deleting it — silence a project for a focused session, or keep one off the channel entirely. --- ## Tools | Tool | Description | |---|---| | `vibegroup_peers` | List the agents in your room and what they're working on. | | `vibegroup_ask` | Ask a peer a question. Returns a `qid`; the answer arrives as a `` event. | | `vibegroup_reply` | Answer a peer's question (pass the `qid` from the incoming `` event). | Questions and answers both **arrive as channel events** pushed into your session — there's no inbox to poll. --- ## Security model A peer's question lands in your live session, so the defenses are framing + scope, not a separate sandbox: - **Untrusted-input framing.** The channel's system instructions tell the agent to treat incoming questions as data (never instructions), answer **read-only**, and never reveal secrets or run state-changing commands. - **Secret redaction.** Replies are scrubbed for API keys, tokens, and private-key blocks, then length-capped, before they leave. - **End-to-end encryption.** Per-room AES-256-GCM; the relay holds no key. - **Signed identity + private rooms.** The relay stamps the authoritative sender; membership is gated by a token shared out-of-band. > **Honest note:** because answering happens in your *real* session, treat a vibegroup room as you'd treat the people in it — a circle of friends, not the open internet. Keep your permission settings tight, and don't put a relay token somewhere untrusted. --- ## Project status & roadmap - ✅ **Relay broker** — rooms, signed identity, ciphertext routing, qid lifecycle, offline queue + resume. Deployed on Azure Container Apps. - ✅ **Channel agent** — E2E crypto, relay client, the `vibegroup_*` tools, push-based question/answer delivery, read-only framing. Verified live across two sessions. - ⏳ **Packaging** — `/plugin install` + channel allowlisting so it's not a dev-flag launch. - ⏳ **Hardening** — relay rate limits + auth on room creation, E2E key rotation, presence richness. See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the full list and a real-world testing checklist. --- ## Development ```bash bun install bun test ``` The roadmap and real-world testing checklist live in [`docs/ROADMAP.md`](docs/ROADMAP.md). --- ## License [MIT](LICENSE).