codex-telegram-bridge

A local bridge that lets you control Codex from Telegram and receive Codex notify events in Telegram.

Features

• Telegram long-polling bridge for Codex CLI
• Per-chat session handling (resume latest, resume specific session, or force new session)
• Image support (codex exec ... -i <image>)
• Codex notify forwarding to Telegram
• Optional local Linux desktop/audio notifications (notify-send + paplay)

Project Layout

• bridge.py: main Telegram polling + Codex bridge
• notify_telegram.py: sends Codex notify payloads to Telegram
• notify_all.sh: notify hook wrapper (Telegram + optional desktop/audio notification)
• .env.example: configuration template
• reset_codex_sessions.sh: helper to clear ~/.codex/sessions/* and truncate ~/.codex/history.jsonl

Requirements

• Python 3.12+
• codex available in PATH
• Telegram bot token
• Your Telegram user ID and/or username in the allowlist

Installation

1. Clone:

git clone <your-repo-url> /path/to/codex-telegram-bridge
cd /path/to/codex-telegram-bridge

2. Create .env from the template:

cp .env.example .env

3. Install Python dependencies:

python3 -m pip install -r requirements.txt

4. Edit .env with your real values.

5. Configure Codex notify hook in ~/.codex/config.toml:

notify = ["/path/to/codex-telegram-bridge/notify_all.sh"]

6. Start the bridge:

python3 /path/to/codex-telegram-bridge/bridge.py

Configuration

Default env path:

• /path/to/codex-telegram-bridge/.env

Optional env override:

• TELEGRAM_BRIDGE_ENV_PATH
• TELEGRAM_BRIDGE_STATE_PATH

Core variables

• BOT_TOKEN: Telegram bot token
• NOTIFY_CHAT_ID: chat where notify_telegram.py sends notify events
• ALLOWED_USERNAMES: comma-separated usernames (without @ preferred)
• ALLOWED_USER_IDS: comma-separated Telegram numeric user IDs
• DEFAULT_CWD: default working directory if /new is used without an explicit path
• CODEX_BIN: Codex binary path/name (default codex)
• POLL_TIMEOUT_SECONDS: Telegram polling timeout (default 30)
• POLL_SLEEP_SECONDS: sleep after polling errors (default 1.0)
• CODEX_TIMEOUT_SECONDS: timeout for Codex command execution (default 900)
• SKIP_GIT_REPO_CHECK: true|false (default true)
• LOG_LEVEL: debug|info|warn|error (default info)

Optional desktop/audio notify variables (notify_all.sh)

• DESKTOP_NOTIFY_TITLE (default Codex)
• DESKTOP_NOTIFY_MESSAGE (default Response ready)
• NOTIFY_AUDIO_PATH (default $HOME/scripts/codex-done.oga)

If paplay is missing, audio is skipped. If the audio file does not exist, audio is skipped.

Telegram Commands

• /help
• /sessions
• /resume
• /resume latest
• /resume new
• /resume <index|session_id>
• /attach <index|session_id>
• /current
• /new
• /new /path
• /new ~
• /new ~/project
• /ask <prompt>

Plain text messages are treated as /ask.

Troubleshooting

• Unauthorized user.
  • ALLOWED_USERNAMES/ALLOWED_USER_IDS is missing or incorrect.
• No sessions found...
  • You do not have local Codex history/session files yet.
• Notification errors
  • Check state/telegram_error.log.
• Invalid cwd
  • Use /new <path> (supports /abs/path, ~, ~/subdir).

Run as a systemd Service (System-Wide)

1. Copy the service template:

sudo cp /path/to/codex-telegram-bridge/systemd/codex-telegram-bridge.service /etc/systemd/system/codex-telegram-bridge.service

2. Edit placeholders in the unit file:

• Replace <your_username> with the Linux user that should run the bridge.
• Keep /path/to/codex-telegram-bridge pointing to your actual clone location.

3. Reload and start:

sudo systemctl daemon-reload
sudo systemctl enable --now codex-telegram-bridge

4. Operate the service:

sudo systemctl status codex-telegram-bridge
sudo journalctl -u codex-telegram-bridge -f
sudo systemctl restart codex-telegram-bridge
sudo systemctl disable --now codex-telegram-bridge

systemd Prerequisites

• python3 installed on the host.
• Dependencies installed with python3 -m pip install -r /path/to/codex-telegram-bridge/requirements.txt.
• codex available in PATH for the service user.
• Valid /path/to/codex-telegram-bridge/.env with required variables.

systemd Troubleshooting

• Service fails immediately:
  • Check logs with sudo journalctl -u codex-telegram-bridge -n 100 --no-pager.
• codex: command not found:
  • Set an absolute binary path in .env, for example:
    • CODEX_BIN=/absolute/path/to/codex
  • Then restart the service:
    • sudo systemctl restart codex-telegram-bridge
  • Alternatively, set PATH explicitly in the systemd unit file for the service user.
• SyntaxError: Unexpected reserved word from codex.js:
  • Your service is likely using an old node binary (for example /usr/bin/node).
  • If codex is installed via nvm, ensure the nvm Node bin path is first in the unit PATH, for example:
    • Environment=PATH=/home/<your_username>/.nvm/versions/node/v22.18.0/bin:/home/<your_username>/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
  • Reload and restart:
    • sudo systemctl daemon-reload
    • sudo systemctl restart codex-telegram-bridge
• Missing/invalid env values:
  • Verify BOT_TOKEN, allowlist variables, and env file path.

Helper: Reset Local Codex Session State

/path/to/codex-telegram-bridge/reset_codex_sessions.sh

This removes everything under ~/.codex/sessions/ and truncates ~/.codex/history.jsonl.