bridge-ws

WebSocket bridge for CLI AI agents — stream Claude, Codex, and Ollama responses over a persistent connection.

Install

npm install -g bridge-ws

Or run without installing:

npx bridge-ws

Quick start

1. Start the server:

bridge-ws

╔═══════════════════════════════════════╗
║          bridge-ws v2.0.2            ║
║     CLI AI Agent Bridge              ║
╚═══════════════════════════════════════╝

Found Claude CLI: 1.x.x
bridge-ws running on ws://localhost:9999
Health check: http://localhost:9999/healthz
Press Ctrl+C to stop

2. Connect and send a prompt:

import WebSocket from "ws";

const ws = new WebSocket("ws://localhost:9999");

ws.on("message", (data) => {
  const msg = JSON.parse(data.toString());

  if (msg.type === "connected") {
    ws.send(JSON.stringify({
      type: "prompt",
      prompt: "Say hello in one sentence.",
      requestId: "req-1",
    }));
  }

  if (msg.type === "chunk") process.stdout.write(msg.content);
  if (msg.type === "complete") ws.close();
  if (msg.type === "error") { console.error(msg.message); ws.close(); }
});

Requirements

• Node.js ≥ 20
• Claude Code CLI (npm install -g @anthropic-ai/claude-code)
• Codex CLI (optional, for provider: "codex")
• Ollama (optional, for provider: "ollama" — no API key needed)

Features

• Request multiplexing — send multiple prompts on a single connection; responses are tagged by requestId
• Streaming — response chunks arrive as they are produced, not after completion
• Cancellation — cancel any in-flight request by requestId
• Three providers — Claude (claude), Codex (codex), and Ollama (ollama) on the same server
• Optional auth — Bearer token authentication via BRIDGE_WS_API_KEY
• Health check — GET /healthz on the same port
• Library-ready — import AgentWebSocketServer directly and inject custom runners

CLI options

Flag	Default	Description
-p, --port <port>	9999	Listen port
-H, --host <host>	localhost	Bind address
-c, --claude-path <path>	claude	Path to Claude CLI
--codex-path <path>	codex	Path to Codex CLI
--ollama-url <url>	http://localhost:11434	Ollama base URL
-t, --timeout <seconds>	300	Per-request CLI timeout
--log-level <level>	info	debug, info, warn, error
--origins <origins>	(any)	Comma-separated allowed origins
--max-turns <n>	(unlimited)	Max Claude agentic turns
--tools <tools>	(all)	Comma-separated Claude tools to enable

Environment variables:

Variable	Description
BRIDGE_WS_API_KEY	Required Bearer token for connecting clients

Protocol

Client → Server

// Send a prompt (provider: "claude" | "codex" | "ollama", defaults to "claude")
{ "type": "prompt", "prompt": "...", "requestId": "req-1", "provider": "claude" }

// Cancel a request
{ "type": "cancel", "requestId": "req-1" }

Server → Client

// On connect
{ "type": "connected", "version": "2.0", "agent": "bridge-ws" }

// Response fragments
{ "type": "chunk", "content": "...", "requestId": "req-1" }

// On completion
{ "type": "complete", "requestId": "req-1" }

// On error or cancellation
{ "type": "error", "message": "...", "requestId": "req-1" }

Full protocol details: docs/reference.md

Concurrent requests

// Both requests run concurrently on the same connection
ws.send(JSON.stringify({ type: "prompt", prompt: "First task", requestId: "a" }));
ws.send(JSON.stringify({ type: "prompt", prompt: "Second task", requestId: "b" }));

ws.on("message", (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.type === "chunk") {
    console.log(`[${msg.requestId}] ${msg.content}`);
  }
});

Authentication

BRIDGE_WS_API_KEY=my-secret bridge-ws

const ws = new WebSocket("ws://localhost:9999", {
  headers: { Authorization: "Bearer my-secret" },
});

Library usage

import { AgentWebSocketServer } from "bridge-ws";
import pino from "pino";

const server = new AgentWebSocketServer({
  port: 9999,
  host: "127.0.0.1",
  logger: pino(),
  apiKey: process.env.BRIDGE_WS_API_KEY,
  maxTurns: 5,
});

await server.start();

Documentation

• Tutorial — step-by-step first run
• How-to guides — auth, tools, cancellation, reverse proxy, library usage
• Reference — all CLI flags, message types, HTTP endpoints
• Explanation — design decisions and architecture

License

MIT