@voxagent/bridge

Local bridge process that pairs the host's Claude Code or Codex agent with a VoxAgent meeting room.

What it does

When a host pairs from the VoxAgent web app, this process:

1. Joins the LiveKit room as a real participant (identity agent:<roomId>).
2. Publishes a synthesized voice track via ElevenLabs (or stays silent in --text-only).
3. Listens on a LiveKit data channel for prompt.user_turn events from any participant.
4. Drives the host's local Claude Code (@anthropic-ai/claude-agent-sdk) or Codex CLI (codex exec --json) agent with the prompt.
5. Streams text deltas, tool calls, and run lifecycle events back to the room — UI gets subtitles + activity timeline, audio track gets the spoken response.

Trust mode by default: the agent runs under the host's existing CLI permission settings, no in-room approval gate.

Quickstart (end users)

You don't need to clone this repo. The bridge is published to npm and runs via npx. The only prerequisites are Node.js (LTS) and your preferred local agent CLI installed + logged in.

# 1. Install your local agent + sign in
#    Claude:  npm i -g @anthropic-ai/claude-code   &&  claude
#    Codex:   npm i -g @openai/codex                &&  codex login

# 2. In your VoxAgent room, click "Pair local agent". Copy the command
#    shown in the dialog. It looks like this (the web UI fills in the
#    code, room-specific api-url, and your selected flags):

npx -y @voxagent/bridge@latest \
  --code 123456 \
  --api-url https://vox-agent-web.vercel.app \
  --agent claude \
  --cwd /path/to/your/workspace

The --api-url flag is the single most common source of confusion: pair codes are scoped to the server that minted them, so the URL on the bridge command MUST match the URL of the web app you generated the code on. The "Pair local agent" UI in the room embeds the correct value automatically; copy the whole command rather than re-typing flags.

Bring-your-own-key for TTS is delivered through the pair flow itself. Save your ElevenLabs / OpenAI key once in /settings/integrations on the web app — the pair payload ships those keys to the bridge process, no export needed in your shell.

Development (contributors)

If you're working on the bridge source directly, the monorepo workflow is:

# Run the web app
pnpm --dir apps/web dev

# In another terminal, run the bridge under tsx watch
pnpm --filter @voxagent/bridge dev -- --code 123456 --agent claude

Or after a build:

pnpm --filter @voxagent/bridge build
node packages/bridge/dist/cli.js --code 123456 --agent claude

Flags

| Flag | Env | Default | Notes | |------|-----|---------|-------| | --code <CODE> | VOXAGENT_PAIR_CODE | (interactive prompt) | 6-digit code from the room UI | | --api-url <URL> | VOXAGENT_API_URL | http://localhost:3000 | VoxAgent web app base URL | | --agent <BACKEND> | VOXAGENT_AGENT | claude | claude or codex | | --cwd <PATH> | VOXAGENT_CWD | process.cwd() | Working directory the agent runs inside | | --voice <VOICE_ID> | VOXAGENT_VOICE_ID | 21m00Tcm4TlvDq8ikWAM | ElevenLabs voice ID | | --model <MODEL_ID> | VOXAGENT_MODEL_ID | eleven_turbo_v2_5 | ElevenLabs model ID | | --text-only | VOXAGENT_TEXT_ONLY=1 | false | Skip TTS — text-only mode (subtitles in UI, no voice) | | --verbose | — | false | Debug logs |

VOXAGENT_ELEVENLABS_API_KEY (or ELEVENLABS_API_KEY) is required unless --text-only is set.

Architecture

See /docs/learning-reviews/ and the refactor plan at /Users/tanmay/.claude/plans/ok-i-want-you-refactored-wadler.md for full background.

Browser  ──LiveKit data channel──▶  Bridge  ──@anthropic-ai/claude-agent-sdk──▶ Claude Code
   ▲                                  │                                       (or `codex exec --json`)
   │                                  ▼
   └────agent voice track────  AudioSource ◀── ElevenLabs PCM ◀── text deltas

Testing

pnpm --filter @voxagent/bridge test

Unit tests mock the SDK and subprocess so they run offline.