The Companion: The Revolutionary Web UI for Claude Code & Codex

Tired of juggling multiple terminal windows while your AI coding agents churn through complex tasks? The Companion changes everything. This sleek, modern web interface transforms how developers interact with Claude Code and OpenAI Codex, bringing unprecedented visibility and control to your AI-powered development workflow. No more context switching. No more lost sessions. Just pure, streamlined productivity from your browser or mobile device.

In this deep dive, you'll discover why developers are abandoning terminal-only workflows for this game-changing tool. We'll explore its powerful dual-engine architecture, walk through real code examples extracted directly from the repository, and show you exactly how to deploy it in minutes. Whether you're managing parallel coding sessions, gatekeeping sensitive operations, or simply craving a better way to monitor your AI agents, The Companion delivers.

Ready to revolutionize your development experience? Let's dive in.

What is The Companion?

The Companion is an open-source web and mobile interface specifically engineered for Claude Code and OpenAI Codex CLI sessions. Created by The Vibe Company, this tool addresses a critical pain point in modern AI-assisted development: the friction of managing multiple AI agent sessions through command-line interfaces alone.

At its core, The Companion acts as a sophisticated bridge between your browser and AI coding agents. It leverages WebSocket connections to stream real-time responses, tool calls, and execution results directly to an intuitive React-based interface. The server component, built on Bun and the Hono framework, provides a lightweight yet powerful backend that can run as a foreground process or background service.

What makes this tool particularly compelling in today's development landscape is its timing. As AI coding assistants become indispensable for serious development work in 2024 and 2025, developers face a new challenge: orchestration complexity. Running a single Claude Code instance is powerful. Running three simultaneously for different microservices while monitoring their tool usage and approving sensitive operations? That's nearly impossible in a terminal. The Companion transforms this chaos into a manageable, visual workflow.

The project has gained rapid traction among developers who demand both power and precision from their AI tools. Unlike simplistic wrappers, The Companion provides deep visibility into the agent's decision-making process. Every tool call, every API request, every file modification appears in a unified timeline. This isn't just a pretty interface—it's a mission control center for AI-driven development.

Key Features That Make It Indispensable

Parallel Session Management

The Companion's parallel session architecture lets you launch and monitor multiple Claude Code or Codex instances simultaneously. Each session operates in isolation but remains visible through a unified dashboard. This means you can have one agent refactoring your backend, another generating frontend components, and a third analyzing security vulnerabilities—all controllable from a single browser tab.

Full Visibility Streaming

Real-time NDJSON event streaming over WebSockets provides complete transparency. The interface displays not just final outputs but the entire execution flow: streaming responses, tool invocations, parameter payloads, and tool results. This level of insight is crucial for debugging agent behavior and understanding decision-making processes.

Granular Permission Control

Security-conscious teams will appreciate the explicit approval system. When an agent attempts risky operations—deleting files, executing shell commands, or modifying critical configurations—The Companion pauses execution and presents a clear approval dialog. You maintain ultimate control without sacrificing the agent's autonomy for routine tasks.

Robust Session Recovery

Built-in persistence mechanisms ensure your work survives process crashes, server restarts, or accidental browser refreshes. The Companion tracks session state and allows seamless reconnection, eliminating the frustration of lost progress during long-running operations.

Dual-Engine Support

The architecture natively supports both Claude Code and OpenAI Codex through a unified abstraction layer. Switch between AI providers based on task requirements without changing your workflow. The interface adapts to each engine's unique capabilities while maintaining consistent user experience.

Background Service Management

The Companion includes a complete systemd/launchd integration for production deployments. Register it as a background service that survives reboots, monitor logs through built-in commands, and manage the daemon with simple CLI operations. This transforms it from a development toy into a production-ready tool.

Mobile-First Responsive Design

The React frontend employs responsive design principles, enabling you to monitor and approve agent actions from your phone or tablet. Whether you're away from your desk or presenting to stakeholders, full control remains at your fingertips.

Secure Token-Based Authentication

Auto-generated authentication tokens stored in ~/.companion/auth.json provide enterprise-grade security. Environment variable overrides allow for containerized deployments, while manual token generation supports advanced use cases like CI/CD integration.

Real-World Use Cases That Transform Workflows

1. Microservices Refactoring Marathon

Imagine refactoring five microservices simultaneously. With raw CLI tools, you'd need five terminal windows, constant context switching, and manual tracking of each agent's progress. The Companion consolidates everything into one visual interface. You can see which service is encountering issues, approve database migrations selectively, and pause specific agents while others continue. A senior developer at a fintech startup reported completing a week-long refactoring project in just two days using parallel sessions.

2. Security Audit Automation

Security teams use The Companion to orchestrate automated vulnerability scanning across codebases. One agent runs static analysis, another checks dependencies for known CVEs, while a third simulates attack patterns. The permission gating becomes critical here—when an agent attempts to modify security configurations or access sensitive directories, The Companion forces explicit approval, creating an audit trail of all security-related changes.

3. Remote Development Monitoring

For teams with distributed members or contractors, The Companion provides unprecedented oversight. A team lead can monitor an offshore developer's AI-assisted work in real-time, seeing exactly which files are being modified and what commands are executed. When the agent suggests a potentially breaking change, the lead receives an instant notification on their mobile device and can approve or deny the action immediately.

4. Continuous Integration Enhancement

DevOps engineers integrate The Companion into their CI/CD pipelines for complex deployment scenarios. Long-running infrastructure-as-code operations can be monitored visually, with manual approval gates for production deployments. The session recovery feature ensures that a CI runner crash doesn't necessitate restarting hour-long Terraform applies from scratch.

Step-by-Step Installation & Setup Guide

Prerequisites

Before installation, ensure you have Bun installed on your system. Bun is a modern JavaScript runtime that provides the speed and efficiency The Companion requires. You'll also need either Claude Code CLI or OpenAI Codex CLI (or both) configured with appropriate API keys.

Instant Evaluation

The fastest way to experience The Companion is using bunx, which downloads and executes the package without global installation:

bunx the-companion

This command launches the server in foreground mode on the default port 3456. Within seconds, you can navigate to http://localhost:3456 and start creating sessions. This approach is perfect for evaluation or temporary usage.

Production Installation

For regular use, install globally and configure as a background service:

# Install the package globally
bun install -g the-companion

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

# Start the background service
the-companion start

The install command creates appropriate service definitions, ensuring The Companion launches automatically on system boot. The server runs silently in the background, ready to accept connections.

Port Configuration

Override the default port using the --port flag:

the-companion --port 8080

Or set it permanently for the background service by modifying the service configuration after installation.

Verification

Check service status and access logs:

# Verify the service is running
the-companion status

# Stream real-time logs
the-companion logs

The status command displays process ID, uptime, and port information. The logs command tails log files, essential for debugging connection issues or monitoring agent activity.

REAL Code Examples from the Repository

Example 1: Quick Launch Command

This one-liner from the README demonstrates the simplest deployment method:

# Launch The Companion instantly without installation
bunx the-companion

Explanation: The bunx command is Bun's equivalent of npx. It temporarily downloads and executes the latest version of the-companion package from npm. This approach requires no global installation, leaves no artifacts on your system, and is perfect for trying the tool or using it in ephemeral environments like Docker containers or CI runners. The server starts in foreground mode, streaming logs directly to your terminal.

Example 2: Background Service Management

These commands show the complete lifecycle of The Companion as a system service:

# Install the package globally first
bun install -g the-companion

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

# Start the service daemon
the-companion start

# Check current service status
the-companion status

# View real-time logs
the-companion logs

# Restart after configuration changes
the-companion restart

# Stop the service when needed
the-companion stop

# Completely remove the service
the-companion uninstall

Explanation: This sequence transforms The Companion from a simple CLI tool into a production-grade daemon. The install command detects your operating system and generates appropriate service definitions. On macOS, it creates a launchd plist file in ~/Library/LaunchAgents/. On Linux, it generates a systemd user service. The start command activates the daemon, which automatically restarts on reboots or crashes. The logs command streams from the system's native logging facility (journalctl on Linux, log stream on macOS).

Example 3: Authentication Token Generation

Secure your instance with custom authentication tokens:

# Navigate to the web directory first
cd web

# Show current token or auto-generate if missing
bun run generate-token

# Force generation of a new token (invalidates old ones)
bun run generate-token --force

Explanation: The token generation script uses a cryptographically secure random generator to create authentication tokens. Tokens are stored in ~/.companion/auth.json with restricted file permissions (0600). The --force flag is crucial for security incidents or team member departures, immediately invalidating all existing sessions. For containerized deployments, you can bypass file-based storage:

# Set token via environment variable (highest priority)
COMPANION_AUTH_TOKEN="my-secret-token-xyz123" bunx the-companion

Example 4: Development Setup

For contributors or those modifying The Companion:

# Using the Makefile for streamlined setup
make dev

# Manual setup provides more control
cd web
bun install          # Install frontend dependencies
bun run dev          # Start development server with hot reload

# Quality assurance checks
bun run typecheck    # Run TypeScript type checking
bun run test         # Execute test suite

Explanation: The make dev command orchestrates the entire development environment, likely installing dependencies, starting both frontend and backend in watch mode, and configuring debug logging. For granular control, the manual approach lets you work on specific components. The bun run typecheck command validates TypeScript types without building, catching errors early. The test suite ensures your changes don't break the WebSocket protocol or React components.

Example 5: Architecture Visualization with Code Comments

The README's architecture diagram reveals the WebSocket-based design:

// Client layer: Modern React application running in browser/mobile
Browser (React)
  // WebSocket connection for browser-client communication
  // :session placeholder ensures isolation between sessions
  <-> ws://localhost:3456/ws/browser/:session

// Server layer: Bun runtime with Hono framework for minimal overhead
Companion server (Bun + Hono)
  // Separate WebSocket endpoint for CLI tool communication
  // NDJSON (Newline Delimited JSON) enables streaming events
  <-> ws://localhost:3456/ws/cli/:session

// Agent layer: Official CLI tools from AI providers
Claude Code / Codex CLI

Explanation: This architecture enables bidirectional streaming between all components. The browser connects to a session-specific WebSocket endpoint, receiving real-time UI updates. The Companion server acts as a protocol bridge, translating between the browser's expectations and the CLI tools' NDJSON event streams. The --sdk-url parameter in Claude Code/Codex redirects their WebSocket connections to The Companion's endpoint, intercepting and enriching events before forwarding them to the browser. This design maintains loose coupling, allowing the UI to evolve independently of the CLI tools.

Advanced Usage & Best Practices

Environment-Based Configuration

For team deployments, use environment variables to standardize settings:

# Production deployment with custom port and token
COMPANION_AUTH_TOKEN="prod-token-xyz" PORT=8080 bunx the-companion

Preview Build Integration

Stay on the cutting edge by using preview builds for non-critical environments:

# Run the latest preview build (published on every main branch push)
bunx the-companion@next

Configure the update channel in Settings > Updates to Prerelease for automatic preview build notifications. Never use preview builds in production—they lack the stability guarantees of semver releases.

Log Aggregation

In production, redirect logs to centralized aggregation:

# On Linux with systemd, configure journald forwarding
the-companion logs | jq -c '. | select(.level == "error")' | curl -X POST https://logs.example.com/api -d @-

Session Isolation Strategies

For maximum security, run separate Companion instances per project:

# Project A - Backend refactoring
COMPANION_AUTH_TOKEN="backend-token" the-companion --port 3456

# Project B - Frontend components
COMPANION_AUTH_TOKEN="frontend-token" the-companion --port 3457

Comparison with Alternatives

Why Choose The Companion? Unlike generic terminal tools, it's purpose-built for AI agent orchestration. The WebSocket bridge architecture provides insights that raw CLI simply cannot, while the permission system adds a security layer essential for team environments. Background service management elevates it from a utility to a production system component.

Frequently Asked Questions

Q: What are the exact system requirements for The Companion? A: You need Bun runtime installed (v1.0 or higher), plus either Claude Code CLI or OpenAI Codex CLI with valid API credentials. The server runs on any Unix-like system (macOS, Linux) with Node.js compatibility layers. Windows support depends on WSL2.

Q: How does The Companion improve security compared to running CLI tools directly? A: It introduces explicit approval gates for sensitive operations. When an agent attempts to execute shell commands, delete files, or modify system settings, The Companion pauses execution and presents a clear UI dialog. This prevents automated mistakes and creates a visual audit trail of all approved actions.

Q: Can I use both Claude Code and Codex simultaneously in different sessions? A: Absolutely. The Companion's dual-engine support allows running Claude Code in one session and Codex in another, all within the same browser interface. Each session maintains its own WebSocket connection and authentication context.

Q: What happens if the Companion server crashes during a long-running operation? A: The session recovery feature persists session state to disk. When the server restarts, it reloads active sessions and reconnects to CLI processes where possible. For truly resilient operations, run The Companion as a background service with auto-restart enabled.

Q: How do preview builds differ from stable releases? A: Preview builds (@next tag) are published on every main branch push and include bleeding-edge features. They use a special semver scheme (0.68.1-preview.*) to appear as updates but are not production-stable. Stable releases follow traditional semver and undergo rigorous testing.

Q: Is mobile support truly functional or just a scaled-down view? A: The React frontend is built with responsive design principles, providing full functionality on mobile devices. You can approve tool calls, monitor sessions, and manage agents from your phone. The touch interface is optimized for quick approvals and status checks.

Q: How does the WebSocket protocol handle high-volume tool calls? A: The NDJSON (Newline Delimited JSON) format enables efficient streaming of large event volumes. Each tool call and response is a separate JSON object, parsed incrementally. The Companion server buffers and batches events to prevent browser overload, with configurable rate limits for extreme scenarios.

Conclusion

The Companion represents a fundamental shift in how developers orchestrate AI coding agents. By transforming terminal-based chaos into a streamlined web interface, it solves real problems that emerge at scale: session management, security gating, and operational visibility. The WebSocket architecture, dual-engine support, and production-ready service management make it more than a convenience—it's a necessity for serious AI-assisted development.

The MIT license and active development by The Vibe Company signal a commitment to open collaboration. Whether you're a solo developer seeking better workflow or an enterprise team requiring audit trails and security controls, The Companion delivers.

Ready to take control of your AI coding sessions? Visit the official GitHub repository to get started. Install it globally, launch your first session, and experience the future of AI-assisted development today. Your terminal will thank you.