Control your local Codex threads from Telegram. Keep working while away from your Mac. 🚀
Quick links: Download · Commands · FAQ · Troubleshooting · Press kit · Report issue
Codex is great on desktop, but it is not remote-first: your work stalls the moment you step away from your machine.
Codex Bridge keeps your real Codex thread alive on your phone, with:
- ✅ Thread-aware remote control (
/threads,/bind,/current) - 🔒 Safe remote execution (approvals:
/approve//deny) - 📊 Status + limits (
/status,/usage) - 🧰 Menu bar controls (online state + remote switch)
- 🌏 Bilingual UX (English + Chinese)
| Desktop app home | Telegram remote control |
|---|---|
 |
 |
- Remote chat with context: keep using the same local Codex thread from Telegram.
- Approvals: when Codex wants to run commands or change files, you can approve/deny from Telegram.
- Queue + cancel: long runs can be cancelled with
/cancel. - Usage: check your remaining limits with
/usage(alias:/limits).
Notes:
- Photo input is experimental and depends on your Codex App / App Server version.
- Per-thread “busy status” is not reliably observable from Codex today (we only know tasks started by this bridge).
- Download the latest desktop build from Releases and open it.
- In the onboarding wizard:
- Environment check (Codex CLI + App Server).
- Configure Telegram bot (paste a BotFather token).
- Pair your phone (QR / deep link).
- In Telegram:
- Send
/threads - Tap a thread button (or
/bind <index>)
- Send
- Send your first remote prompt.
| Command | What it does |
|---|---|
/threads |
List recent threads and bind quickly |
/bind latest |
Bind the latest thread |
/bind <index> |
Bind by list index (from /threads) |
/bind <threadId> |
Bind by thread ID |
/current |
Show snapshot of the current bound thread |
/status |
Show bridge status |
/usage / /limits |
Show Codex rate limits remaining |
/cancel |
Cancel the current task |
/unbind |
Clear current binding |
/threadsis now resilient: ifthread/listis slow/unavailable, it degrades to the Codex sidebar cache so Telegram still gets a fast reply.- Reduced “stuck waiting” cases caused by Keychain prompts/hangs (best-effort Keychain access with short timeouts).
flowchart LR
A["Install app"] --> B["Pair phone in onboarding"]
B --> C["Telegram: /threads"]
C --> D["Pick and bind a thread"]
D --> E["Send remote task"]
E --> F["Receive status + final response"]
flowchart TB
U["Telegram user"] --> T["Telegram bot"]
T --> R["Bridge relay (local on your Mac)"]
R --> A["Desktop agent"]
A --> C["Codex App Server JSON-RPC"]
C --> TH["Selected Codex thread"]
TH --> C --> A --> R --> T --> U
- Commands
- Configuration
- Architecture details
- Operations
- Relay API
- Privacy
- Threat model
- Self-hosting
- Troubleshooting
- FAQ
- Star the repo if it helped you.
- Share a screenshot or a short clip: pairing →
/threads→ first reply. - If you write a post/video about it, open a PR to add it to the README.
npm install
npm run setup
npm run build
npm run start:desktopCodex 在桌面端很强，但它不是“随时随地继续工作”的工具：你一离开电脑，对话就中断。
Codex Bridge 把你的本机 Codex thread 连接到 Telegram，让你在手机上继续推进同一条对话，上下文、审批和回包都保持一致：
- ✅ thread 级远程控制（
/threads、/bind、/current） - 🔒 远程审批（
/approve//deny） - 📊 状态与用量（
/status、/usage） - 🧰 菜单栏快速开关（在线状态 + 远程开关）
- 🌏 双语体验（中 / 英）
| 电脑端主页 | Telegram 远程控制 |
|---|---|
|
|
- 带上下文的远程续聊：不是消息转发，是继续你本机的真实 thread。
- 审批：需要执行命令/修改文件时，可在 Telegram 一键同意/拒绝。
- 队列与终止：长任务可以用
/cancel主动停止。 - 用量：
/usage（别名/limits）查看剩余额度。
说明：
- 图片输入属于实验能力，是否可用取决于你的 Codex App / App Server 版本。
- 每个 thread 的“是否正在运行”目前无法从 Codex 稳定获取（桥接只能知道自己触发的任务）。
- 在 Releases 下载并打开桌面 App。
- 按向导完成：
- 环境检测（Codex CLI + App Server）
- 配置 Telegram 机器人（粘贴 BotFather token）
- 手机配对（扫码或 deep link）
- Telegram 里：
- 发送
/threads - 点选 thread（或
/bind <编号>）
- 发送
- 开始发消息远程操作。
| 命令 | 作用 |
|---|---|
/threads |
查看最近会话并快速绑定 |
/bind latest |
绑定最新会话 |
/bind <编号> |
按 /threads 列表编号绑定 |
/bind <threadId> |
按 threadId 绑定 |
/current |
查看当前会话快照 |
/status |
查看桥接状态 |
/usage / /limits |
查看剩余用量与重置时间 |
/cancel |
终止当前任务 |
/unbind |
解除绑定 |
/threads更稳：thread/list超时会降级到 Codex 侧边栏缓存，确保 Telegram 仍能快速拿到列表。- 降低 Keychain 造成的“卡住/无回包”风险（Keychain 访问改为短超时 best-effort）。