vibe-bridge

CLI bridge for Vibe Relay — relay Claude Code agent events to your Mac.

Prerequisites

• Node.js >= 20
• A running Vibe Relay server (you'll need the relay URL and a setup key)

Install & Setup

Run setup with your relay URL and setup key (from the Vibe Relay app):

npx vibe-bridge setup claude --relay=https://your-relay.example.com --key=<setup_key>

Setup copies the bridge runtime to ~/.vibe-bridge/ and injects hooks pointing to ~/.vibe-bridge/bin/vibe-bridge. After setup, the bridge runs independently — you don't need a global install or node_modules.

This does the following:

1. Exchanges the setup key for a device token via POST /api/setup
2. Saves config to ~/.vibe-bridge/config.json
3. Copies bridge files to ~/.vibe-bridge/lib/ and creates a launcher at ~/.vibe-bridge/bin/vibe-bridge
4. Injects hooks into ~/.claude/settings.json
5. Sends a test event to verify connectivity

Verify

Check that everything is configured:

vibe-bridge status

Expected output:

Status: configured
  Relay: https://your-relay.example.com
  Machine ID: m_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  Source: claude

Send a test event to confirm the relay connection works:

vibe-bridge test

Verify hooks

List injected Claude Code hooks:

vibe-bridge hooks list

This should show all subscribed events:

Injected hooks:
  PreToolUse
  PostToolUse
  Notification
  PermissionRequest
  Stop
  SessionStart
  SessionEnd
  SubagentStart
  SubagentStop
  PreCompact
  UserPromptSubmit

Usage

Once set up, vibe-bridge works automatically. Claude Code will invoke it via hooks on every agent event. No manual intervention needed.

• Fire-and-forget events (PostToolUse, Notification, etc.) are sent async and never block Claude Code.
• PermissionRequest events are synchronous — the relay app can approve/deny tool calls. If the relay is unreachable, Claude Code falls back to its terminal prompt.

Commands

| Command | Description | |---|---| | vibe-bridge setup <source> --relay=<url> --key=<key> | Pair with a relay server | | vibe-bridge status | Show current config | | vibe-bridge test | Send a test event | | vibe-bridge update | Reinstall bridge files and re-inject hooks | | vibe-bridge unpair | Remove config and hooks | | vibe-bridge hooks list | List injected hooks | | vibe-bridge hooks inject <source> | Re-inject hooks | | vibe-bridge hooks remove <source> | Remove hooks |

Troubleshooting

"Not configured" error

Run setup again:

vibe-bridge setup claude --relay=<url> --key=<key>

Hooks not firing

Re-inject hooks manually:

vibe-bridge hooks inject claude

Then verify they're in ~/.claude/settings.json:

vibe-bridge hooks list

Connection issues

1. Check that the relay server is reachable: curl <relay_url>/api/event
2. Run vibe-bridge test to send a test event
3. Check that ~/.vibe-bridge/config.json has the correct relay_url and device_token

Update after upgrading

After a new version is published, re-sync local files:

npx vibe-bridge@latest update

File layout

~/.vibe-bridge/
  config.json          # relay_url, device_token, machine_id, source, timeout
  bin/vibe-bridge      # launcher script (shell wrapper → node lib/cli.js)
  lib/                 # bridge runtime (copied from dist/)

~/.claude/
  settings.json        # Claude Code settings with injected hooks