The Companion

用于 Claude Code 和 Codex 会话的 Web UI。

运行多个代理，检查每一次工具调用，并通过明确的批准来控制高风险操作。

快速入门

要求： Bun + Claude Code 和/或 Codex CLI。

立即试用

bunx the-companion

打开 http://localhost:3456。

全局安装

bun install -g the-companion

# 注册为后台服务（macOS 上为 launchd，Linux 上为 systemd）
the-companion install

# 启动服务
the-companion start

打开 http://localhost:3456。服务器将在后台运行，并在重启后继续工作。

CLI 命令

命令	描述
the-companion	在前台启动服务器（默认）
the-companion serve	在前台显式启动服务器
the-companion install	注册为后台服务（launchd/systemd）
the-companion start	启动后台服务
the-companion stop	停止后台服务
the-companion restart	重启后台服务
the-companion uninstall	移除后台服务
the-companion status	显示服务状态
the-companion logs	实时查看服务日志文件

选项： --port <n> 可覆盖默认端口（3456）。

使用价值

• 并行会话：无需切换终端即可同时处理多项任务。
• 全面可见性：在一个时间轴上查看流式输出、工具调用及工具结果。
• 权限控制：从 UI 中批准或拒绝敏感操作。
• 会话恢复：在进程或服务器重启后恢复工作。
• 双引擎支持：专为基于 Claude Code 和 Codex 的流程设计。

截图

聊天 + 工具时间轴	权限流程

架构（简要）

浏览器（React）
  <-> ws://localhost:3456/ws/browser/:session
Companion 服务器（Bun + Hono）
  <-> ws://localhost:3456/ws/cli/:session
Claude Code / Codex CLI

该桥接使用 CLI 的 --sdk-url WebSocket 路径和 NDJSON 事件。

身份验证

服务器在首次启动时会自动生成一个身份验证令牌，存储在 ~/.companion/auth.json 中。你也可以手动管理令牌：

# 显示当前令牌（或自动生成一个）
cd web && bun run generate-token

# 强制重新生成一个新令牌
cd web && bun run generate-token --force

或者通过环境变量设置令牌（优先于文件中的令牌）：

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

开发

make dev

手动：

cd web
bun install
bun run dev

检查：

cd web
bun run typecheck
bun run test

预览版 / 预发布版本

每次向 main 分支推送代码，都会发布一个预览版构建：

构建	标签 / dist-tag	示例
Docker 镜像（滚动更新）	preview-main	docker.io/stangirard/the-companion:preview-main
Docker 镜像（不可变）	preview-<sha>	docker.io/stangirard/the-companion:preview-abc1234...
npm 包	next	bunx the-companion@next

预览版构建会进行核心补丁升级（例如，当稳定版为 0.68.0 时，预览版为 0.68.1-preview.*），以便应用内的更新检查器能够将其识别为比当前稳定版更高的语义版本号。这些版本并非生产级稳定版——请使用 latest 或语义版本标签来获取稳定版。

在应用内跟踪预发布更新

在 设置 > 更新 中，将更新通道切换到 预发布，即可接收预览版构建。默认通道为 稳定（仅接收语义版本发布）。切换通道会在下一次检查更新时立即生效。

文档

• 完整文档：docs/（Mintlify — 运行 cd docs && mint dev 即可在本地预览）
• 协议逆向工程：WEBSOCKET_PROTOCOL_REVERSED.md
• 贡献者与架构指南：CLAUDE.md

许可证

MIT

Companion 快速上手指南

Companion 是一个专为 Claude Code 和 Codex 会话设计的 Web UI 工具。它支持并行运行多个 Agent 会话，提供完整的工具调用可视化，并允许用户在执行高风险操作前进行显式审批。

环境准备

在开始之前，请确保您的系统已安装以下依赖：

• 运行时环境: Bun (必需)
  • 安装命令 (Linux/macOS): curl -fsSL https://bun.sh/install | bash
  • 国内加速提示：如遇网络问题，可尝试配置国内镜像源或使用代理。
• AI 命令行工具: 至少安装以下其中之一
  • Claude Code CLI
  • Codex CLI

安装步骤

您可以选择“即时试用”或“全局安装并作为后台服务运行”。

方式一：即时试用（推荐首次体验）

无需安装，直接通过 bunx 运行：

bunx the-companion

运行成功后，在浏览器打开：http://localhost:3456

方式二：全局安装（作为后台服务）

适合长期开发使用，服务可在重启后自动恢复。

1. 全局安装包:

   bun install -g the-companion
   

2. 注册为后台服务 (macOS 使用 launchd, Linux 使用 systemd):

   the-companion install
   

3. 启动服务:

   the-companion start
   

4. 访问界面: 打开浏览器访问 http://localhost:3456

提示: 如需修改默认端口，可在命令后添加 --port <端口号> 参数。

基本使用

启动服务并打开 Web 界面后，即可开始使用：

1. 创建会话: 在 Web 界面中新建一个会话，选择底层引擎（Claude Code 或 Codex）。
2. 并行工作: 您可以同时开启多个标签页处理不同任务，无需在终端间切换。
3. 监控与审批:
   • 全链路可视: 实时查看流式输出、工具调用参数及执行结果。
   • 权限管控: 当 AI 尝试执行敏感操作（如文件写入、命令执行）时，界面会弹出确认框，需您手动点击“批准”或“拒绝”后方可继续。
4. 会话恢复: 即使服务器或进程重启，之前的工作会话状态也会自动保留，可随时恢复。

常用管理命令

命令	说明
the-companion stop	停止后台服务
the-companion restart	重启后台服务
the-companion status	查看服务运行状态
the-companion logs	实时查看服务日志
the-companion uninstall	卸载后台服务

认证令牌 (可选)

服务器首次启动会自动生成认证令牌并保存至 ~/.companion/auth.json。如需手动管理或通过环境变量指定：

# 通过环境变量设置令牌（优先级高于文件）
COMPANION_AUTH_TOKEN="my-secret-token" bunx the-companion