Codex Companion

中文：把本地 codex app-server 接到 Telegram 私聊，让你在手机上驱动电脑里的 Codex。
English: Bridge a local codex app-server into Telegram private chat so you can drive Codex on your computer from your phone.

Features / 特性

• 手机发消息，本机 Codex 执行 / Send commands from Telegram, run them on your local Codex runtime
• 复用本机工作目录、认证状态和运行数据 / Keep workspace access, auth state, and runtime data on your own machine
• 支持 profile 控制 / Profile controls for model, effort, speed, plan, and permissions
• 支持审批确认 / Approval prompts for higher-risk actions such as full access
• 支持结果回传 / Return status, diffs, files, logs, and resume actions back to Telegram

Demo / 演示

Quick Start / 快速开始

中文：第一次使用，直接看 QUICKSTART.md。
English: If this is your first time, start with QUICKSTART.md.

最小启动路径 / Minimum path:

1. 安装 Node.js 22+、codex CLI，并完成本机 codex login
   Install Node.js 22+, install codex CLI, and complete local codex login
2. 克隆仓库并安装依赖
   Clone the repo and install dependencies
3. 复制 config/companion.toml.example 为 config/companion.toml，填入你自己的路径
   Copy config/companion.toml.example to config/companion.toml and replace the paths
4. 设置 TELEGRAM_BOT_TOKEN，启动 daemon，然后在 Telegram 里 /pair <code>
   Set TELEGRAM_BOT_TOKEN, start the daemon, then send /pair <code> in Telegram

git clone <repo-url>
cd <repo-dir>
npm ci

Windows PowerShell:

Copy-Item config\companion.toml.example config\companion.toml
$env:TELEGRAM_BOT_TOKEN = "123456:telegram-bot-token"
.\scripts\start-companion.ps1

macOS / Linux:

cp config/companion.toml.example config/companion.toml
export TELEGRAM_BOT_TOKEN="123456:telegram-bot-token"
npm run build
npm run start

Requirements / 环境要求

• Node.js 22+
• npm
• codex CLI on PATH
• A locally authenticated Codex runtime
• A Telegram bot token

Common Commands / 常用命令

• /pair <pairing-code>
• /status
• /profile
• /resume
• /interrupt
• 普通文本消息 / plain text messages

示例 / Example:

/profile set model=gpt-5.4 effort=low speed=fallback plan=default permission=full

Config And Data / 配置与数据

• 配置样例 / Example config: config/companion.toml.example
• SQLite 状态 / SQLite state: data/companion.db
• Turn 产物 / Turn artifacts: data/<threadId>/<turnId>.*

中文：TELEGRAM_BOT_TOKEN 只通过环境变量传入，不写进配置文件。
English: TELEGRAM_BOT_TOKEN must be passed through the environment, not the config file.

Current Status / 当前状态

• 仅支持 Telegram 私聊 / Private chats only
• 每个 workspace alias 同时仅允许一个 active turn / Exactly one active turn per workspace alias
• Full access 需要二次确认 / Full access requires a second confirmation
• 当前推荐通过 GitHub 源码方式运行 / The current recommended distribution path is GitHub source install

Development Direction / 开发方向

• 更接近 Codex 原生能力 / Closer Codex-native controls
• 更丰富的本地与 IDE 背景信息 / Richer local and IDE context
• 更容易安装、打包和分发 / Easier installation, packaging, and distribution
• 更强的稳定性、恢复能力和 smoke 覆盖 / Better reliability, recovery, and smoke coverage