<div align="center">🤖 Telecodex</div>

<div align="center"> <strong>Telegram as a remote, topic-aware frontend for your local Codex CLI.</strong> </div> <div align="center"> Long polling. Persistent sessions. Attachment handling. Topic-aware workspace sync. SQLite ACLs. </div> <br /> <div align="center">

</div> <div align="center">

🇷🇺 Русская версия • 📄 MIT License

</div>

---

✨ What it is

Telecodex is a Rust bridge that connects a local codex CLI instance to Telegram.

It turns Telegram chats and forum topics into lightweight remote workspaces where you can:

• talk to Codex from your phone or desktop Telegram client,
• keep separate sessions per chat/topic,
• switch between existing Codex threads,
• send files and media into a turn,
• receive streamed progress and generated artifacts back in Telegram.

No webhook infrastructure. No browser dependency. No cloud relay between Telegram and your local Codex process.

🔥 Why it is useful

• Remote terminal vibe, but usable: Telegram becomes the UI, Codex stays local.
• Topic-aware sessions: each forum topic can map to its own workspace/session.
• Safer multi-user access: SQLite-backed allowlist with admin and user roles.
• Practical file flow: attachments go into a turn inbox, output files come back automatically.
• Session memory without chaos: import local Codex Desktop/CLI history by cwd.
• Codex-first runtime: Telecodex mirrors Codex sessions and settings instead of running its own local scheduler.

🧠 Core capabilities

Conversation and session model

• Polls Telegram Bot API via getUpdates.
• Maintains one logical session per Telegram chat/topic pair.
• Queues turns per session and streams progress by editing Telegram messages in place.
• Supports /new, /environments, /sessions, /use, /clear, /stop, and per-session runtime settings.
• Can bind a Telegram topic to an existing Codex thread by thread id or latest.
• In the primary forum dashboard, environments are listed for import and topics are created on button click by default.

Attachments and artifacts

• Accepts text, images, documents, audio, and video attachments.
• Stages incoming files under:

<session cwd>/.telecodex/inbox/...

• Expects generated deliverables under:

<session cwd>/.telecodex/turns/.../out

• Sends resulting files back to Telegram automatically.

Audio transcription

• Optional audio transcription via ffmpeg + transcribe-rs.
• Auto-detects a local Handy Parakeet model directory when present.
• If transcription succeeds, the transcript is appended to the user prompt.

Access control and safety

• SQLite-backed ACL with allowed, admin, and user role handling.
• Unauthorized access attempts are ignored and written to audit_log.
• Supports Codex runtime defaults for sandbox, approval policy, search mode, and writable directories.
• Supports headless Codex device login from Telegram via /login and /logout.
• If Codex is not logged in, Telecodex does not start turns or forward /status; it asks the user to authenticate first.

History and topic sync

• Reads local Codex history and imports existing sessions by cwd.
• Can sync forum topics from Codex Desktop and/or CLI history.
• Can target a dedicated Telegram forum chat for all new topics.
• Supports stale topic cleanup on a timer.

🏗️ How it works

Telegram chat/topic
        ↓
     Telecodex
        ↓
 local codex CLI
        ↓
  workspace files
        ↓
 Telegram edits + artifacts

High-level flow:

1. Telegram sends updates through long polling.
2. Telecodex resolves the active session for the current chat/topic.
3. Incoming text and attachments are converted into a Codex turn request.
4. Codex runs locally in the configured workspace.
5. Progress is streamed back by editing Telegram messages.
6. Files produced in the turn output directory are uploaded back to Telegram.

🛠️ Command model

Bridge-handled commands

| Command | Purpose | | --- | --- | | /new [title] | Start a fresh Codex session in the current topic/chat | | /topic [title] | Create a new Telegram topic and copy the current environment into it | | /use <thread_id_prefix\|latest> | Switch this Telegram session to an existing Codex thread | | /review [--uncommitted] [--base BRANCH] [--commit SHA] [--title TITLE] [prompt] | Run codex review-style flows | | /login | Start headless Codex device login, send a clickable auth link, and show the one-time code inline | | /logout | Remove stored Codex credentials | | /cd <absolute_path> | Change the session working directory | | /pwd | Show the current working directory | | /environments | Show importable Codex environments in the primary forum dashboard | | /sessions | Show sessions available in the current chat | | /stop | Stop the active turn | | /model [model\|default\|-] | Set or show the current model | | /think [minimal\|low\|medium\|high\|default\|-] | Set or show reasoning effort | | /prompt [text\|clear\|default\|-] | Set or clear the persistent session prompt | | /approval <never\|on-request\|untrusted> | Set approval policy | | /sandbox <read-only\|workspace-write\|danger-full-access> | Set sandbox mode | | /search <on\|off\|cached> | Set search behavior | | /add-dir <absolute_path> | Add a writable directory | | /limits | Show Codex rate limits | | /copy | Re-send the last assistant reply | | /clear | Force a fresh session on the next turn | | /allow <tg_user_id> | Admin: allow a Telegram user | | /deny <tg_user_id> | Admin: deny a Telegram user | | /role <tg_user_id> <admin\|user> | Admin: assign role | | /restart_bot | Admin: restart the bot process |

Forwarded to Codex as-is

/help, /status, /doctor, /prompts, /memory, /mentions, /init, /bug, /config, /compact, /agents, /diff

These commands require an active Codex login. If the local Codex CLI is not authenticated yet, Telecodex will remind the user to run /login instead of forwarding them.

Explicitly unsupported in Telegram

/theme, /vim, /statusline, /browser, /ide, /notifications, /terminal-setup

⚙️ Requirements

Required

• Rust 1.85+
• a working local codex CLI available on PATH or configured explicitly
• Telegram bot token
• go-task

Optional but recommended

• ffmpeg for audio/video conversion
• a local Handy Parakeet model for speech transcription

🚀 Quick start

1. Clone and enter the repo

git clone https://github.com/Headcrab/telecodex.git
cd telecodex

2. Create the config

task init-config

This creates telecodex.toml from telecodex.toml.example if it does not exist.

3. Set your Telegram bot token

Set TELEGRAM_BOT_TOKEN in your environment before launch. Example:

export TELEGRAM_BOT_TOKEN="123456:replace-me"

4. Edit telecodex.toml

Minimal example:

db_path = "telecodex.sqlite3"
startup_admin_ids = [123456789]
poll_timeout_seconds = 30
edit_debounce_ms = 900
max_text_chunk = 3500
tmp_dir = "/absolute/path/to/telecodex/tmp"

[telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
api_base = "https://api.telegram.org"
use_message_drafts = true

[codex]
binary = "codex"
default_cwd = "/absolute/path/to/telecodex"
default_model = "gpt-5.4"
default_reasoning_effort = "medium"
default_sandbox = "workspace-write"
default_approval = "never"
default_search_mode = "disabled"
import_desktop_history = true
import_cli_history = true
seed_workspaces = ["/absolute/path/to/workspace-a"]
default_add_dirs = ["/absolute/path/to/workspace"]

5. Run it

task run

6. Log in to Codex from Telegram

After the bot starts, open the Telegram chat with your bot and run:

/login

Telecodex will start codex login --device-auth, send a clickable auth.openai.com link, show the one-time code inline in the message for quick copying, and post the result in chat when the login finishes.

🧩 Configuration notes

Telegram

• telegram.bot_token or telegram.bot_token_env must be configured.
• telegram.use_message_drafts = true enables draft-style previews for private chats.
• telegram.primary_forum_chat_id is used by /topic to create topics in one dedicated forum.
• telegram.auto_create_topics = false keeps environment import manual; set it to true to auto-create missing forum topics from history.
• telegram.forum_sync_topics_per_poll throttles topic sync work.
• telegram.stale_topic_days + telegram.stale_topic_action = "close"|"delete" enable cleanup.

Codex

• codex.binary can be a binary name or absolute path.
• codex.default_cwd must be an existing absolute directory.
• codex.seed_workspaces adds explicit workspace directories to /environments and forum sync, even before they have local Codex history.
• codex.default_add_dirs entries must also be absolute existing directories.
• codex.import_desktop_history and codex.import_cli_history control session import sources.
• codex.default_search_mode supports disabled, live, and cached.

Environment variables

• TELEGRAM_BOT_TOKEN: Telegram Bot API token.
• TELECODEX_RESTART_DELAY_MS: optional startup delay before boot.

📁