takopi/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. From this folder, run the entrypoints with uv run (uses pyproject.toml deps).
3. Put your Telegram credentials in ~/.codex/telegram.toml.

Example ~/.codex/telegram.toml:

bot_token = "123:abc"
chat_id = 123456789

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

Optional flags:

• --progress-edit-every FLOAT (default 2.0)
• --progress-silent/--no-progress-silent (default silent)
• --final-notify/--no-final-notify (default notify via new message)
• --ignore-backlog/--process-backlog (default ignore pending updates)

Option 2: MCP server

Run:

uv run mcp-bridge

Optional flags:

• --ignore-backlog/--process-backlog (default ignore pending updates)

Option 3: tmux

Reply injector:

uv run tmux-reply

Optional flags:

• --ignore-backlog/--process-backlog (default ignore pending updates)

Notifier (call from your existing hook):

uv run tmux-notify --tmux-target "codex1:0.0" --text "$TURN_TEXT"

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

Files

• src/codex_telegram_bridge/constants.py: limits and config path constants
• src/codex_telegram_bridge/config.py: config loading and chat-id parsing helpers
• src/codex_telegram_bridge/exec_render.py: renderers for codex exec JSONL events
• src/codex_telegram_bridge/rendering.py: markdown rendering + chunking
• src/codex_telegram_bridge/routes.py: sqlite routing store
• src/codex_telegram_bridge/telegram_client.py: Telegram Bot API client
• src/codex_telegram_bridge/exec_bridge.py: codex exec + resume bridge
• src/codex_telegram_bridge/mcp_bridge.py: MCP stdio JSON-RPC bridge
• src/codex_telegram_bridge/tmux_notify.py: tmux notifier helper
• src/codex_telegram_bridge/tmux_reply_bot.py: tmux reply injector