The Companion

Web UI for Claude Code and Codex sessions.

Run multiple agents, inspect every tool call, and gate risky actions with explicit approvals.

About this fork. This repository is an independent continuation of the original the-vibe-company/companion. Upstream has since pivoted to a Go control plane for agent-fleet management (deploying fleets of agents on Fly + Tailscale) and archived the original web UI. This fork continues that original path instead: unattended web access to Claude-CLI / Codex instances — run multiple agents in the browser, inspect every tool call, and gate risky actions with explicit approvals. It is maintained independently and no longer tracks upstream.

Quick start

Requirements: Bun + Claude Code and/or Codex CLI.

Try it instantly

bunx the-companion

Open http://localhost:3456.

Install globally

bun install -g the-companion

# Register as a background service (launchd on macOS, systemd on Linux)
the-companion install

# Start the service
the-companion start

Open http://localhost:3456. The server runs in the background and survives reboots.

CLI commands

Command	Description
the-companion	Start server in foreground (default)
the-companion serve	Start server in foreground (explicit)
the-companion install	Register as a background service (launchd/systemd)
the-companion start	Start the background service
the-companion stop	Stop the background service
the-companion restart	Restart the background service
the-companion uninstall	Remove the background service
the-companion status	Show service status
the-companion logs	Tail service log files

Options: --port <n> overrides the default port (3456).

Why this is useful

• Parallel sessions: work on multiple tasks without juggling terminals.
• Full visibility: see streaming output, tool calls, and tool results in one timeline.
• Permission control: approve/deny sensitive operations from the UI.
• Session recovery: restore work after process/server restarts.
• Dual-engine support: designed for both Claude Code and Codex-backed flows.

Screenshots

Chat + tool timeline	Permission flow

Architecture (simple)

Browser (React)
  <-> ws://localhost:3456/ws/browser/:session
Companion server (Bun + Hono)
  <-> ws://localhost:3456/ws/cli/:session
Claude Code / Codex CLI

The bridge uses the CLI --sdk-url websocket path and NDJSON events.

Authentication

The server auto-generates an auth token on first start, stored at ~/.companion/auth.json. You can also manage tokens manually:

# Show the current token (or auto-generate one)
cd web && bun run generate-token

# Force-regenerate a new token
cd web && bun run generate-token --force

Or set a token via environment variable (takes priority over the file):

COMPANION_AUTH_TOKEN="my-secret-token" bunx the-companion

Development

make dev

Manual:

cd web
bun install
bun run dev

Checks:

cd web
bun run typecheck
bun run test

Preview / Prerelease

Every push to main publishes a preview artifact:

Artifact	Tag / dist-tag	Example
Docker image (moving)	preview-main	docker.io/croll83/the-companion:preview-main
Docker image (immutable)	preview-<sha>	docker.io/croll83/the-companion:preview-abc1234...
npm package	next	bunx the-companion@next

Preview builds use a patch-core bump (e.g. 0.68.1-preview.* when stable is 0.68.0) so the in-app update checker can detect them as semver-ahead of the current stable release. They are not production-stable — use latest / semver tags for stable releases.

Tracking prerelease updates in-app

In Settings > Updates, switch the update channel to Prerelease to receive preview builds. The default channel is Stable (semver releases only). Switching channels takes effect immediately on the next update check.

Docs

• Full documentation: docs/ (Mintlify — run cd docs && mint dev to preview locally)
• Protocol reverse engineering: WEBSOCKET_PROTOCOL_REVERSED.md
• Contributor and architecture guide: CLAUDE.md

License

MIT