teledex

Lightweight Telegram bridge for persistent Codex sessions

teledex turns Telegram into a practical remote control layer for Codex with persistent sessions, bound working directories, live draft previews, and final result delivery.

Overview

teledex is a Telegram -> Codex control bridge designed around real project directories and persistent execution context.

Instead of trying to become a full platform, it focuses on the core remote workflow: send a command or plain message from Telegram, route it into the correct Codex session and working directory, keep one preview message updated during execution, and send the final result back when the run is done.

Features

• Telegram long-polling message flow
• Whitelist-based access control
• Multiple sessions with create, list, and switch actions
• Per-session working directory binding
• Persistent tmux terminal per bound directory
• Codex runs executed inside the persistent terminal context
• Live draft preview updates inside a single Telegram message
• /tstop support for interrupting the current run
• SQLite persistence for users, sessions, and run state

Tech Stack

• Service implementation: Python 3.11+
• Messaging interface: Telegram Bot API
• State storage: SQLite, sqlite3
• Codex bridge: tmux, codex CLI, app-server
• Deployment: local long-running process, systemd

Project Structure

src/teledex/
  __main__.py              CLI entry
  app.py                   Telegram loop and command dispatch
  config.py                Environment variable parsing
  storage.py               SQLite persistence layer
  codex_runner.py          tmux terminal startup and Codex event parsing
  codex_app_server_exec.py Codex execution wrapper
  telegram_api.py          Telegram HTTP API client
  formatting.py            Markdown/HTML rendering and message splitting
deploy/
  teledex.service          systemd service example

Quick Start

1. Install the project.

pip install -e .

2. Copy the environment template.

cp .env.example .env.local

3. Fill in the required values in .env.local.

• TELEGRAM_BOT_TOKEN
• AUTHORIZED_TELEGRAM_USER_IDS

4. Start the service.

set -a
source .env.local
set +a
teledex

If you prefer to run it without installing the script entrypoint:

set -a
source .env.local
set +a
PYTHONPATH=src python3 -m teledex

By default, runtime state is stored in ./data/teledex.sqlite3.

Configuration

The repository ships with a ready-to-copy .env.example. Core variables:

• TELEGRAM_BOT_TOKEN: Telegram Bot Token
• AUTHORIZED_TELEGRAM_USER_IDS: allowed Telegram user IDs, comma-separated
• TELEDEX_STATE_DIR: local state directory, default ./data
• TELEDEX_POLL_TIMEOUT_SECONDS: Telegram long-poll timeout, default 30
• TELEDEX_PREVIEW_UPDATE_INTERVAL_SECONDS: unified preview interval, used for both heartbeat refresh and minimum Telegram edit spacing, default 5.0
• TELEDEX_CODEX_BIN: path to the Codex executable, default codex
• TELEDEX_CODEX_EXEC_MODE: Codex execution mode, supports default, full-auto, dangerous; default default, which preserves the local Codex approval and sandbox configuration
• TELEDEX_CODEX_MODEL: optional Codex model override
• TELEDEX_CODEX_ENABLE_SEARCH: whether search is enabled
• TELEDEX_TMUX_BIN: path to the tmux executable, default tmux
• TELEDEX_TMUX_SHELL: shell used to start the tmux session, defaults to SHELL or /bin/bash
• TELEDEX_LOG_LEVEL: log level, default INFO

Telegram Commands

• /start: show help text
• /tbind <absolute-path>: bind the working directory and start the persistent tmux terminal; it creates the session on first bind and reuses it on later binds
• /tpwd: show the bound directory
• /tstop: stop the current task
• /twipe: wipe the current user's teledex state

All other /commands are forwarded directly into the active Codex session.

Plain text messages are sent to the current active session and executed inside its bound directory.

Runtime Model

• Each authorized user keeps an active session pointer
• Each session can be bound to a real project directory
• Binding a directory starts a persistent tmux terminal for that session
• The first run creates a Codex thread, and later messages try to reuse it inside the same terminal context
• One Telegram preview message is refreshed continuously while the task runs
• Final output and run status are written back after completion

systemd Deployment

The repository includes a sample service file at deploy/teledex.service.

Typical deployment flow:

cp deploy/teledex.service /etc/systemd/system/teledex.service
systemctl daemon-reload
systemctl enable --now teledex
systemctl status teledex

For production use, keep .env.local and the data directory in a stable path and let systemd manage the process lifecycle.

Use Cases

• Continue desktop Codex sessions from your phone
• Keep separate execution context for multiple project directories
• Watch long-running tasks through live preview updates
• Run a lightweight Telegram control layer on a VPS

Security Note

Current access control mainly depends on an allowed-user whitelist.

That means you should protect:

• your Bot Token
• filesystem permissions of the account running teledex
• exposure of trusted working directories
• host-level process and network isolation when deployed publicly

teledex is intentionally a lightweight bridge, not a multi-tenant platform. Add extra controls if you plan to expose it beyond a trusted environment.