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

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

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.1
File	Size	Uploaded
codex_telegram-0.5.1.tar.gz	324.5 kB	Sep 25, 2026	Details

Built distribution (wheel)

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

Total release size: 626.0 kB

Release files / codex_telegram-0.5.1.tar.gz

Download URL	codex_telegram-0.5.1.tar.gz
Size	324.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`7c1a1d9fd48db83068ca493caf05ce0e4f9207e38986e37af5a1427884b3f4e9`
BLAKE2b-256 checksum How to use checksums	`ba2cea25ce776be3538e36780c4852825c89902ccb6df2275f38cfdf01739a88`
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.1-py3-none-any.whl

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