🌉 Codex Server Bridge

Control your Codex coding agents from Telegram. No terminal switching required.

---

You're on the couch. Your phone buzzes — a Codex task just finished. You open Telegram, tap Open 2, scan the diff, tap Reply with "now add tests", and go back to dinner.

That's the workflow.

---

The Problem

Codex is powerful, but managing threads means juggling terminals, browser tabs, and desktop apps. Context-switching kills flow — especially when you're away from your desk.

The Solution

codex-server-bridge turns your chat app into a full Codex control plane:

Action	How
📋 List threads	Tap /codex — get a paginated dashboard with inline buttons
🔍 Open a thread	Tap Open 2 — see status, model, last activity
👀 Watch live	Tap Watch — stream real-time progress summaries
💬 Reply	Tap Reply → type your message → new turn kicks off
🎯 Steer	Redirect an in-flight turn without interrupting
🛑 Interrupt	Stop a runaway task with confirmation safety gate
📄 Export	Full transcript as .txt, sent right to your chat

All from your phone. All without opening a terminal.

Demo

📋 Codex Dashboard (3 of 6)
───────────────────────────
1. refactor auth middleware     ✅ completed  2m ago
2. add payment webhooks         🔄 in progress
3. fix flaky e2e tests          ✅ completed  18m ago

[Open 1] [Open 2] [Open 3] [Show Next] [Refresh] [UI Off]

🔍 Thread #2 — add payment webhooks
────────────────────────────────────
Status:    🔄 in progress
Model:     gpt-5.3-codex
Started:   3 min ago
Turns:     4

[Watch] [Last 3] [Last 10] [Transcript]
[Reply] [Steer] [Interrupt] [← Back]

Quick Start

1. Install as an OpenClaw skill

# From your OpenClaw workspace
cp -r codex-server-bridge ~/.openclaw/skills/
# Or symlink it
ln -s $(pwd)/codex-server-bridge ~/.openclaw/skills/codex-server-bridge

2. Make sure Codex is running

codex --version   # Codex CLI must be in PATH

3. Use it

Just tell your OpenClaw agent:

• /codex — open the dashboard
• "show my codex tasks"
• "watch task 2"
• "reply to task 1 with: add error handling"

The skill handles everything else.

How It Works

flowchart LR
    TG[Telegram chat UI] <--> AGENT[OpenClaw agent\nSKILL.md contract]
    AGENT <--> BRIDGE[codex_tasks.js\nbridge CLI]
    BRIDGE <--> CODEX[codex app-server\nlocal process]

Loading

The bridge speaks JSON-RPC over stdio to codex app-server, translates responses into chat-friendly UI with inline buttons, and maintains per-session state so thread indexes stay consistent across interactions.

CLI Reference

The bridge CLI can also be used standalone:

# List threads
node scripts/codex_tasks.js list --limit 6 --session my-session

# Open thread details
node scripts/codex_tasks.js open --index 2 --session my-session

# Watch live output (30s window)
node scripts/codex_tasks.js watch --index 2 --timeout 30 --session my-session

# Start a new task
node scripts/codex_tasks.js start --prompt "refactor the auth module" --session my-session

# Reply to a thread
node scripts/codex_tasks.js reply --index 2 --text "now add tests" --session my-session

# Steer an active turn
node scripts/codex_tasks.js steer --index 2 --text "focus on edge cases" --session my-session

# Interrupt with confirmation
node scripts/codex_tasks.js interrupt --index 2 --confirm --session my-session

# Export full transcript
node scripts/codex_tasks.js transcript --index 2 --out ./thread-2.txt --session my-session

Safety

This isn't a YOLO bridge. Safety is built in:

• interrupt requires --confirm — no accidental kills
• steer/interrupt validate active turns — can't steer a completed thread
• start enforces a cwd allowlist — tasks can only run in approved directories
• Overload protection — exponential backoff + jitter on -32001 errors

Configuration

Environment Variable	What it does	Default
CODEX_BRIDGE_ALLOWLIST	Comma-separated allowed cwd paths for start	Current working directory
CODEX_SESSION_INDEX	Path to Codex session index (for thread titles)	~/.codex/session_index.jsonl

Requirements

• Node.js 20+
• Codex CLI in PATH with app-server support
• OpenClaw (or compatible orchestrator) with inline button support

What's Inside

codex-server-bridge/
├── SKILL.md                    # OpenClaw skill instructions + UX contract
├── scripts/
│   ├── codex_tasks.js          # JSON-RPC bridge CLI (the engine)
│   └── codex_ui_state.js       # Per-chat composer state helper
├── references/
│   └── protocol.md             # Codex app-server protocol notes
├── .state/                     # Runtime state (gitignored)
├── package.json
├── LICENSE                     # MIT
└── README.md                   # You are here

Contributing

This was extracted from a production OpenClaw workflow. If you adapt it to other chat platforms (Discord, Slack, WhatsApp), PRs are welcome.

License

MIT © Jonathan Limon