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.2

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.2
File	Size	Uploaded
codex_telegram-0.5.2.tar.gz	326.2 kB	Sep 25, 2026	Details

Built distribution (wheel)

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

Total release size: 628.7 kB

Release files / codex_telegram-0.5.2.tar.gz

Download URL	codex_telegram-0.5.2.tar.gz
Size	326.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`30d5fd4462c8cf512b69ed654da87f3857dfb572cf9ca32e3a6bfaf91c69a18a`
BLAKE2b-256 checksum How to use checksums	`cb8b0e611fc2722f590d4b320b43565b67259c702bf2f85d2c01741b9937e2d4`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`

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

Download URL	codex_telegram-0.5.2-py3-none-any.whl
Size	302.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6e67b792810a05639a46c75c8d421c7aec6206afb5ed130742e2e7bd96c25591`
BLAKE2b-256 checksum How to use checksums	`3dc02161cfe2fffb68d5fdda7e4a0a8273ef66810b9cdcf2fc3ae66530ca7574`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`