vibeshare

Share your live agent coding session by URL — traces.com-style, open source, CLI-first. Spectators watch read-only; invite links let viewers request to join as collaborators (host approves, live).

Part of the Vibe Suite — companion tools for agentic coding CLIs (Claude Code, Codex, Gemini, Grok/pi, Kimi). Ships as CLI + npm package + MCP server, built on @pooriaarab/vibe-core (consent ledger, hooks bus, badges).

Local-first: the share runs on your machine. The consent ledger gates every share (share:session scope), the stream is served straight from your host, and nothing is stored on a server.

Works with any harness

vibeshare shares a LIVE TERMINAL SESSION. It wraps a PTY, so the program inside is irrelevant — any agent CLI, shell, or TUI renders faithfully (colors, cursor, full-screen) via xterm.js in the browser.

Two ways to share a session:

• Wrap at launch (no tmux): vibeshare --public -- <harness> — vibeshare is the parent, PTY-captures. Examples: vibeshare --public -- claude, -- codex, -- gemini, -- aider, -- opencode, -- kimi, -- amp, or any shell/command.

• Attach to an already-running session (needs tmux): run the harness inside tmux, then vibeshare attach <pane> taps it live. Harness-agnostic — it captures the terminal, not the app.

Verified harnesses (all render the real TUI live): Claude Code (claude), OpenAI Codex (codex), Gemini CLI (gemini), aider (requires pip install aider-chat), opencode, Moonshot Kimi (kimi), pi (grok/glm), Sourcegraph amp (requires its own PATH setup). Others (Continue, Goose, Crush, Qwen, Cursor Agent, Warp, Zed, …) wrap identically — they're just terminal programs.

Modes: --public (WebRTC P2P + e2e via getvibe.dev), --tunnel <provider> (12 providers, e2e), or local loopback/LAN. Presence + attributed chat included.

Related MCP server: spectatty

Demo

▶ Watch the launch video — claude is multiplayer now.

https://github.com/pooriaarab/vibeshare/raw/main/branding/launch-video.mp4

Install & build

npm install
npm run build      # tsup → dist/ (cli.js, index.js, mcp.js + types)
npm run typecheck  # tsc --noEmit
npm test           # vitest

CLI

vibeshare                        # share your shell, spectate read-only
vibeshare --invite --expire 1h   # viewers may request to join; auto-expires
vibeshare --pass hunter2         # passphrase second factor
vibeshare -- npm test            # share a specific command
vibeshare --host 0.0.0.0         # share on your LAN (default: loopback only)

vibeshare viewers                # who's watching, pending join requests
vibeshare viewers --approve <id> # promote a viewer to collaborator
vibeshare viewers --kick <id>    # remove a viewer, live
vibeshare stop                   # end the share (works from another terminal)

Running vibeshare prints the link:

● local · no data out
  sharing:  npm test
  url:      http://127.0.0.1:50613/s/KKxzdjLpr_km
  access:   spectate (read-only)
  expires:  until you stop
  manage:   vibeshare viewers · vibeshare stop

Opening the URL shows a self-contained spectator page (no install for viewers) streaming the session live over SSE, with a "Request to join" button on invite links. First run asks for consent (--yes to skip); the grant is recorded locally in ~/.vibeshare/consent.json and can be revoked any time.

Read-only is real: there is no route that lets a viewer write — the host is the server of record, and promotion to collaborator goes only through a host-approved request (ViewerRegistry.canWrite() is the single gate).

Reliable connectivity (TURN)

--public shares are peer-to-peer with STUN only by default (free, no infra) — that works across most NATs. If viewers sit behind symmetric NATs or isolated networks and get stuck on "waiting for host", add a TURN relay: ICE config is set on the host and automatically propagated to viewers over signaling, so both ends use it.

Precedence, highest first:

1. --ice-servers '<json>' CLI flag — a JSON array of RTCIceServer objects

2. VIBESHARE_ICE_SERVERS env var (same JSON)

3. ~/.vibeshare/config.json → "iceServers" key

4. default: [{ "urls": "stun:stun.l.google.com:19302" }] (STUN only)

// ~/.vibeshare/config.json — self-hosted coturn, or a provider
// (metered.ca, Twilio, Cloudflare Calls TURN, …)
{
  "iceServers": [
    { "urls": "stun:stun.l.google.com:19302" },
    {
      "urls": "turn:turn.example.com:3478",
      "username": "vibeshare",
      "credential": "long-lived-or-temporary-secret"
    }
  ]
}

The credentials are the host's own (short-lived tokens by convention); they travel over the signaling channel to viewers so the browser can reach the relay. Malformed flag/env JSON is reported and skipped — resolution falls through to the next source, never breaking the share.

npm library

import { createShare, grantConsent } from 'vibeshare';

grantConsent('share from my tool');              // once; local ledger
const { url, feed, viewers, revoke } = await createShare({
  session: 'npm test',
  access: 'spectate',                            // or 'invite'
  expiry: '1h',                                  // or 'stop'
});

feed.publish('tests starting…');
viewers.on('request', (v) => viewers.approve(v.id));
await revoke();

createShare throws ConsentRequiredError without a share:session grant. Bring your own plumbing with ShareManager, LocalHttpTransport, and FileConsentStore.

MCP server

{
  "mcpServers": {
    "vibeshare": { "command": "vibeshare-mcp" }
  }
}

Tools: vibeshare_create, vibeshare_viewers, vibeshare_stop — so an agent can offer "share this session?". Your MCP client's tool-approval prompt is the consent act (recorded with that note). Approving join requests stays human-only, via the CLI.

Architecture & the vibelive seam

vibeshare owns the link + gate; session content is an ordered feed served to spectators. The one deliberate seam is transport (src/transport.ts):

• LocalHttpTransport (implemented, default): spectator page + SSE stream + loopback host-control API, served from your machine. Nothing stored on a server.

• RelayTransport (lands with vibelive): a dumb e2e relay / p2p mesh handing out public vibeshare.io URLs — same ShareTransport interface, swap-in only. Collaborator input routing is part of that seam and must pass ViewerRegistry.canWrite().

Everything else — consent, access policy, passphrase gate, expiry teardown, viewer registry, revocation — is fully implemented and tested.

Prototype

The original UX prototype (no build, no network): open docs/prototype.html. Spec: docs/spec.md.