The Problem
Claude Code is powerful but locked into a terminal interface. Developers cannot easily run multiple sessions simultaneously, there is no visual feedback on tool calls, and if the CLI process dies, all context is lost. Managing sub-agent hierarchies and approval flows in a terminal is cumbersome and error-prone.
What This Does
The Vibe Companion is a web UI that reverse-engineers Claude Code's hidden --sdk-url flag to spawn CLI processes from a browser. It connects to the CLI via WebSocket using an NDJSON protocol (web/server/ws-bridge.ts), streaming responses token-by-token (web/src/ws.ts). The server (web/server/index.ts) manages session lifecycles, worktree tracking (web/server/worktree-tracker.ts), and permission approval flows through four modes configured in web/src/components/PermissionBanner.tsx. Multiple sessions run side-by-side, each with independent processes and model settings. Tool calls appear as collapsible blocks with syntax highlighting, and sub-agent nesting renders hierarchically so the full chain is visible. Sessions persist to disk and auto-recover with --resume (web/server/session-store.ts).
How To Use It
Setup: git clone https://github.com/The-Vibe-Company/companion.git cd companion/web bun install
Configuration: Copy .env.example and set required variables. The file defines expected environment configuration (.env.example).
Running it: bun run dev # starts backend + Vite HMR on :5174 or production: bun run build && bun run start # serves on :3456
Open localhost:3456. No API key is needed if you have an existing Claude Code subscription.
Real-World Use
A distributed team wants to run parallel code review sessions without terminal overhead. They launch three Companion sessions from browser tabs, each spawning claude --sdk-url ws://localhost:3456/ws/cli/SESSIONID. As the agents write code, the browser streams responses live. When a Bash command or Edit tool is invoked, the UI shows the operation in a collapsible block with syntax highlighting. A developer reviews and approves or denies the tool call without leaving the browser. If the CLI crashes, sessions auto-recover on restart via saved state.
Code Health & Issues
No test files detected - repository-wide untested code paths. No test infrastructure is present in the file structure. Reverse-engineered protocol - the WebSocket protocol (WEBSOCKETPROTOCOL_REVERSED.md) is undocumented by Anthropology; changes to the CLI could break compatibility without notice. No lockfile evidence - bun.lock exists in the root, but the heuristic flag notes dependencies declared without a lockfile for reproducible builds. Verify lockfile consistency. CI/CD configured - GitHub Actions workflow (.github/workflows/publish.yml) is present, but test coverage is absent. Secrets handling - environment variables via .env.example; ensure production deployments do not commit real keys.
The Bottom Line
This is a functional bridge between a browser and Claude Code's SDK protocol, enabling visual session management and tool approval without terminal dependency. It works well for individual developers or small teams needing multiple concurrent Claude Code instances. The reverse-engineered protocol is the main risk point - protocol drift in CLI updates will require maintenance. For teams comfortable with a thin SDK layer and wanting browser-based Claude Code workflows, this is a practical solution; for mission-critical dependability on unmodified CLI versions, the protocol volatility is a concern.