Codex Telegram + Web

A bridge that lets you control the Codex App Server from Telegram and Web UI.

Features

Telegram Bot

Control Codex directly from Telegram:

Slash commands: /start, /resume, /projects, /review, /exec, and more
Real-time updates: Receive progress notifications and turn completions
Interactive approvals: Approve/deny dangerous operations with inline buttons
Multi-project support: Switch between projects with /project <name>
Thread management: Start, resume, fork, archive conversations

Web UI

ChatGPT-style interface with advanced features:

Streaming responses: Real-time message streaming via SSE
Multi-project tabs: Each project has independent workspace context
Thread tabs: Multiple conversations per project
Workspace browser: File tree, Git status, file preview, diff viewer
Settings panels: Features, Models, Modes, Skills, Apps, MCP, Guardian
Dark/Light theme: Theme toggle with localStorage persistence
Responsive design: Desktop and mobile layouts

Shared Features

Approval workflow: Interactive approve/deny for sensitive operations
Guardian: Policy-based safety rules to auto-approve or escalate requests
Real-time events: Live updates via SSE (Web) and push notifications (Telegram)
Multi-project: Manage multiple projects with separate thread histories

Requirements

Python 3.11+
Telegram Bot Token (if Telegram enabled)
Installed and runnable codex CLI
Web UI: password and allowed users configured

Find your Telegram user ID: https://t.me/userinfobot

Quick Start

1. Install

pip install codex-telegram

If installation fails, try:

# Upgrade pip first
pip install --upgrade pip

# Install with system packages flag (some Linux distributions)
pip install codex-telegram --break-system-packages

# Or install for current user only
pip install codex-telegram --user

# Or use a virtual environment
python -m venv .venv && source .venv/bin/activate
pip install codex-telegram

Update

The CLI checks for updates automatically on startup. When a newer version is available on PyPI, you'll see:

✨ Update available! 0.5.1 -> 0.5.2

  Release notes: https://github.com/heungtae/codex-telegram/releases/latest

  1. Update now and exit (runs `pip install -U codex-telegram`)
  2. Skip this run
  3. Skip this version

  Choose [1/2/3] (default: 2):

You can also update manually:

pip install -U codex-telegram

Or with system packages flag:

pip install -U codex-telegram --break-system-packages

2. Configure

Create ~/.config/codex-telegram/conf.toml:

project = "default"

[projects.default]
name = "my project"
path = "/path/to/your/project"

[telegram.bot]
token = "YOUR_TELEGRAM_BOT_TOKEN"

[users]
allowed_ids = [123456789]

3. Run

codex-telegram

Or with environment variables:

export TELEGRAM_BOT_TOKEN="your_token"
export CODEX_WEB_PASSWORD="your_password"
codex-telegram

If you want to rebuild the web UI before launching the app, use:

./run_build_and_main.sh

Or:

make run

4. Open Web UI

http://127.0.0.1:8080

Developing from Source

git clone https://github.com/heungtae/codex-telegram.git
cd codex-telegram
pip install -e .
cd web/frontend && npm install && npm run build && cd ../..
cp conf.toml.example ~/.config/codex-telegram/conf.toml
# Edit config, then run:
./run_build_and_main.sh

Documentation

File	Description
TELEGRAM.md	Telegram bot commands, real-time updates, approval workflow
WEB.md	Web UI features, API endpoints, workspace browser
conf.toml.example	Full configuration reference

Security

Keep users.allowed_ids populated with trusted Telegram user IDs only
Use environment variables for tokens: TELEGRAM_BOT_TOKEN, CODEX_WEB_PASSWORD
Run one polling instance per bot token to avoid conflicts
Set cookie_secure = true when using HTTPS

License

Apache License 2.0. See LICENSE for details.

Release files for codex-telegram 0.5.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for codex-telegram 0.5.9
File	Size	Uploaded
codex_telegram-0.5.9.tar.gz	326.4 kB	Sep 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for codex-telegram 0.5.9
File	Interpreter	ABI	Platform	Reset
codex_telegram-0.5.9-py3-none-any.whl 302.7 kB Sep 25, 2026	Python 3	none	any	Details

Total release size: 629.1 kB

Release files / codex_telegram-0.5.9.tar.gz

Download URL	codex_telegram-0.5.9.tar.gz
Size	326.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`3aee293a08e2ae32ab9b5e836d8cc18bd4abf5d44e7e4456e1a640211f36466b`
BLAKE2b-256 checksum How to use checksums	`6b2baabe22151607c3b12cb3416fae871d2e7830ea93489cee21bfa8ed56305e`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / codex_telegram-0.5.9-py3-none-any.whl

Download URL	codex_telegram-0.5.9-py3-none-any.whl
Size	302.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`77d4a04eef9fc48cbb32e37a0d638e57c77c01638bbb83ab3fa32244e19f5f11`
BLAKE2b-256 checksum How to use checksums	`4be453ce38389647d502b495f1b4ea52af9497a0c2135e80a3e158c45d74335e`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`