takopi/codex/codex_telegram_bridge/readme.md

Telegram Codex Bridge (Codex)

Route Telegram replies back into Codex sessions. Includes three options:

1. Non-interactive codex exec + codex exec resume.
2. codex mcp-server with MCP stdio JSON-RPC.
3. tmux injection for interactive Codex sessions.

All options store a mapping from (chat_id, bot_message_id) to a route so replies can be routed correctly.

Install

1. Ensure uv is installed.
2. Use the scripts in this folder as-is (no extra dependencies).
3. Put your Telegram credentials in ~/.codex/telegram.toml.

Example ~/.codex/telegram.toml:

bot_token = "123:abc"
chat_id = 123456789

For Python < 3.11, install tomli to read TOML. chat_id is used both for allowed messages and startup notifications.

Optional keys (by mode):

• common: bridge_db, allowed_chat_ids, startup_chat_ids
• exec/resume: startup_message, codex_cmd, codex_workspace, codex_exec_args, max_workers
• MCP server: codex_mcp_cmd, codex_workspace, codex_sandbox, codex_approval_policy

Option 1: exec/resume

Run:

uv run exec_bridge.py

Option 2: MCP server

Run:

uv run mcp_bridge.py

Option 3: tmux

Reply injector:

uv run tmux_reply_bot.py

Notifier (call from your existing hook):

uv run tmux_notify.py --tmux-target "codex1:0.0" --text "$TURN_TEXT"

Add --chat-id if chat_id is not set in ~/.codex/telegram.toml.

Files

• bridge_common.py: shared Telegram client, chunking, and routing store
• exec_bridge.py: codex exec + resume bridge
• mcp_bridge.py: MCP stdio JSON-RPC bridge
• tmux_notify.py: tmux notifier helper
• tmux_reply_bot.py: tmux reply injector