vibegroup

<h1 align="center">vibegroup ☎️</h1>

<p align="center"> <strong>Build with your team, and let your agents do the same.</strong><br> Claude Code sessions that talk to each other across repos, machines, and networks. </p>

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, 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 <channel source="vibegroup" kind="question" …>, their agent answers read-only and calls vibegroup_reply.
Receiving is a push too: the answer routes back and pushes into your session as <channel kind="answer" …>.

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 (this repo) | the channel: relay client, E2E crypto, the vibegroup_* tools, and the Claude Code plugin | | vibegroup-relay | the broker you host — rooms, signed identity, ciphertext routing. Never decrypts anything. | | 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). Share the room + token with your team out-of-band.

3. Launch the session as a channel

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.

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). 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 <channel kind="answer"> event. | | vibegroup_reply | Answer a peer's question (pass the qid from the incoming <channel kind="question"> 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 for the full list and a real-world testing checklist.

---

Development

bun install
bun test

The roadmap and real-world testing checklist live in docs/ROADMAP.md.

---

License

MIT.