<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>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"></a>
  <img src="https://img.shields.io/badge/status-alpha-orange" alt="Status: alpha">
  <img src="https://img.shields.io/badge/tests-67_passing-brightgreen" alt="67 tests passing">
  <img src="https://img.shields.io/badge/runtime-Bun-000000?logo=bun&logoColor=white" alt="Bun">
  <img src="https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white" alt="TypeScript strict">
  <img src="https://img.shields.io/badge/Claude_Code-Channel-5a45ff" alt="Claude Code Channel">
  <img src="https://img.shields.io/badge/E2E-AES--256--GCM-1f6feb" alt="End-to-end encrypted">
  <img src="https://img.shields.io/badge/macOS_%7C_Linux-supported-lightgrey" alt="macOS | Linux">
</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](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 `<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](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 `<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`](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).