Control local Codex tasks from Telegram with a durable worker, secure account pairing and private runtime storage. Supports macOS and Linux.
Requires Node.js 24, npm and Python 3.10+. Linux autostart uses a systemd user session. Create your bot through BotFather, then run this in your own terminal:
npx --yes --package github:boundlessend/codex-telegram-bridge codex-telegram-bridge setupThe wizard asks for a trusted Git project and a hidden bot token. Open its
one-time Telegram link to bind your account, then choose whether to start the
services automatically. No numeric user ID, .env editing or manual service
files are needed. It checks your existing Codex login and offers login only
when required; the read-only SDK check uses your normal account.
Stop an older bridge polling the same bot before pairing. Dependencies and
runtime code are installed in a permanent private folder outside plugin caches.
For repeat commands, use the same npx prefix with doctor, status, start,
stop, restart or uninstall instead of setup.
The plugin is available through Senya Plugins:
codex plugin marketplace add boundlessend/yougile-tracking
codex plugin marketplace upgrade senya-plugins
codex plugin add codex-telegram-bridge@senya-pluginsInvoke $codex-telegram-bridge for setup or maintenance help. The skill keeps
token input in your local terminal. Removing the plugin does not stop its
independent daemon: run the bridge's uninstall command first when retiring it.
Uninstall unregisters user services and keeps local settings and history.
Send /start, then a small task. Verify complete delivery with
Reply exactly TELEGRAM_CODEX_OK without tools.
Use /menu, /new, /resume, /queue, /settings, /status, /doctor and
/stop. Defaults are workspace-write and on-request. Full Access remains
available with confirmations retained. Interactive approvals cannot be accepted
from Telegram; perform those operations locally.
Images belong in the project's outputs/ folder. File metadata is cleaned
before sending; PNG/JPEG/PDF require exiftool, and PDF also needs qpdf.
GIF/WebP are refused. Cleaning does not redact private content.
/cleanup_uploads previews files; deletion requires Confirm upload cleanup.
See setup and configuration, security and rollback. Keep credentials, state and logs out of Git.
npm ci
npm run verify
npm run audit:ciCI verifies macOS and Linux on Node.js 24. Tests require OpenSSL. See architecture and release checks. Node.js 26 has a known Telegraf multipart upload issue; the wizard requires 24.
Original additions: BSD-3-Clause. Incorporated upstream code retains MIT; preserve both notices and NOTICE. This is a community project, unaffiliated with OpenAI or Telegram.