vibeshare-live

vibeshare

通过 URL 分享实时 Agent 编码会话——采用 traces.com 风格，开源，以 CLI 为先。旁观者只能查看；邀请链接允许查看者申请加入成为协作者（由主机实时审批）。

属于 Vibe Suite——为 Agent 编码 CLI（Claude Code、Codex、Gemini、Grok/pi、Kimi）提供的配套工具。以 CLI + npm 软件包 + MCP 服务形式发布，基于 @pooriaarab/vibe-core 构建（同意记录、钩子总线、徽章）。

本地优先：分享在你的机器上运行。 同意记录会控制每次分享（share:session scope），数据流直接由你的主机提供，不会存储在服务器上。

兼容任何运行环境

vibeshare 分享的是实时终端会话。它会封装 PTY，因此内部运行的程序并不重要——任何 Agent CLI、Shell 或 TUI 都能通过浏览器中的 xterm.js 忠实呈现（包括颜色、光标和全屏效果）。

分享会话的两种方式：

• 启动时封装（无需 tmux）： vibeshare --public -- <harness> — vibeshare 作为父进程运行，并通过 PTY 捕获内容。例如：vibeshare --public -- claude、-- codex、-- gemini、-- aider、-- opencode、-- kimi、-- amp，或任何 Shell/命令。
• 连接到已运行的会话（需要 tmux）： 在 tmux 中运行运行环境，然后执行 vibeshare attach <pane>，即可实时接入。与运行环境无关——它捕获的是终端，而不是应用。

已验证的运行环境（均可实时呈现真实 TUI）：Claude Code（claude）、OpenAI Codex（codex）、Gemini CLI（gemini）、aider（需要 pip install aider-chat）、opencode、Moonshot Kimi（kimi）、pi（grok/glm）、Sourcegraph amp（需要自行设置 PATH）。其他工具（Continue、Goose、Crush、Qwen、Cursor Agent、Warp、Zed，……）也能以相同方式封装——它们都只是终端程序。

需求	命令
分享新的 claude 会话	vibeshare --public -- claude
分享正在运行的会话	在 tmux 中运行 + vibeshare attach <pane>
仅在本地分享	vibeshare -- <cmd>

模式： --public（通过 getvibe.dev 使用 WebRTC P2P + 端到端加密）、--tunnel <provider>（12 个提供商，端到端加密），或本地回环/LAN。包含在线状态和带发言者标识的聊天。

演示

▶ 观看发布视频 — claude 现在支持多人协作。

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

安装与构建

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)

运行 vibeshare 会打印链接：

● 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

打开 URL 后会显示一个独立的旁观者页面（查看者无需安装），通过 SSE 实时传输会话内容；邀请链接上还会显示“申请加入”按钮。首次运行时会请求同意（使用 --yes 可跳过）；授权记录保存在本地 ~/.vibeshare/consent.json 中，随时可以撤销。

只读权限名副其实：没有任何路由能让查看者写入——主机是唯一的权威服务器；提升为协作者只能通过主机批准的申请进行（ViewerRegistry.canWrite() 是唯一的权限关卡）。

可靠连接（TURN）

默认情况下，--public 分享仅使用 STUN 进行点对点连接（免费，无需基础设施）——这适用于大多数 NAT。如果查看者位于对称 NAT 或隔离网络之后，并卡在“等待主机”状态，可添加 TURN 中继：ICE 配置在主机上设置，并通过信令自动传递给查看者，因此双方都会使用该配置。

优先级从高到低：

1. --ice-servers '<json>' CLI 标志 — RTCIceServer 对象的 JSON 数组
2. VIBESHARE_ICE_SERVERS 环境变量（相同 JSON）
3. ~/.vibeshare/config.json → "iceServers" 键
4. 默认值：[{ "urls": "stun:stun.l.google.com:19302" }]（仅 STUN）

// ~/.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"
    }
  ]
}

这些凭据由主机提供（通常是短时令牌）；它们会通过信令通道传递给查看者，以便浏览器连接到中继。格式错误的标志/环境变量 JSON 会被报告并跳过——解析会继续使用下一个来源，不会导致分享中断。

npm 库

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();

如果没有 share:session 授权，createShare 会抛出 ConsentRequiredError。你可以自行接入 ShareManager、LocalHttpTransport 和 FileConsentStore。

MCP 服务

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

工具：vibeshare_create、vibeshare_viewers、vibeshare_stop，让 Agent 可以询问“分享此会话吗？”。MCP 客户端的工具审批提示就是同意操作（并会记录该备注）。审批加入请求仍仅限人工通过 CLI 进行。

架构与 vibelive 接口

vibeshare 负责链接与访问门控；会话内容以有序信息流的形式提供给旁观者。唯一刻意保留的接口是传输层（src/transport.ts）：

• LocalHttpTransport（已实现，默认）：旁观者页面 + SSE 信息流 + 环回主机控制 API，均由你的机器提供服务。不会在服务器上存储任何内容。
• RelayTransport（随 vibelive 上线）：简单的端到端中继 / P2P 网状网络，用于分发公开的 vibeshare.io URL——实现相同的 ShareTransport 接口，可直接替换。协作者输入路由也是该接口的一部分，必须通过 ViewerRegistry.canWrite()。

其他所有功能——同意、访问策略、密码短语门控、过期后拆除、旁观者注册表、撤销——均已完整实现并经过测试。

原型

原始 UX 原型（无需构建，无网络）：打开 docs/prototype.html。规范：docs/spec.md。