Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
scripts
scripts
 
 
src
src
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
approve-pair.cmd
approve-pair.cmd
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
setup.cmd
setup.cmd
 
 
start.cmd
start.cmd
 
 

Repository files navigation

Telegram Codex Bridge

A cleaner Windows release package for controlling codex app-server from Telegram.

This repo is organized so end users only need a few entry points at the root:

  • setup.cmd
  • start.cmd
  • approve-pair.cmd
  • README.md

Everything else is grouped into src/ and scripts/.

Repository

What It Does

  • chat with Codex from Telegram
  • optionally run a live local mirror console at the same time
  • switch workspace, session, model, mode, and permission
  • restart the runtime from Telegram
  • pause the whole bridge with /shutdown and resume it with /start
  • show account and quota status from Codex Manager
  • switch Codex accounts from Telegram when Codex Manager data is available

Requirements

  • Windows
  • Node.js 22 or newer
  • Codex CLI installed and available as codex
  • a Telegram bot token from @BotFather

Optional but recommended:

  • Codex Manager Required only for /accounts, /switch_acc, and quota details in /status.

Clean Project Structure

.
|-- approve-pair.cmd
|-- package.json
|-- README.md
|-- setup.cmd
|-- start.cmd
|-- scripts/
|   |-- launch-console.cmd
|   |-- register-startup-task.ps1
|   |-- setup.ps1
|   `-- start-bot.cmd
`-- src/
    |-- codex-manager-electron-helper.js
    |-- console-client.js
    |-- index.js
    `-- lib/
        `-- codex-transport.js

Quick Start

This is the intended user flow:

  1. Double-click setup.cmd
  2. Paste the Telegram bot token when asked
  3. Let setup install dependencies and start the bot
  4. Open the bot in Telegram and send /pair
  5. Double-click approve-pair.cmd
  6. Paste the pairing code
  7. Send /menu in Telegram and start using it

What setup.cmd Does

setup.cmd calls scripts/setup.ps1, which:

  • checks that node, npm, and codex are installed
  • verifies Node.js 22+
  • runs npm install
  • asks for TELEGRAM_BOT_TOKEN
  • saves the token in the current user's environment variables
  • optionally starts the bridge immediately

Root Commands

setup.cmd

First-run installer for normal users.

start.cmd

Starts the Telegram bridge through the restart wrapper.

approve-pair.cmd

Approves a Telegram pairing code. You can either:

  • double-click it and paste the code
  • or run approve-pair.cmd ABC123

Telegram Commands

  • /start
  • /menu
  • /help
  • /status
  • /models
  • /mode
  • /permission
  • /permission default
  • /permission full_access
  • /workspace
  • /set_workspace D:\path\to\project
  • /accounts
  • /switch_acc 1
  • /new_session
  • /restart
  • /stop
  • /shutdown
  • /pair

Main Features

Local Mirror Console

The bridge can open a second console window that mirrors runtime activity.

  • set ENABLE_LOCAL_MIRROR=1 to auto-open it
  • or launch it manually with .\scripts\launch-console.cmd
  • or keep it disabled for a cleaner background setup

When the mirror is running, you can:

  • watch prompts coming from Telegram
  • watch assistant replies
  • inspect tool and activity events
  • send prompts locally into the same runtime

Pause vs Stop

  • /stop interrupts only the current turn
  • /shutdown pauses the whole bridge and blocks new prompts or mutating actions
  • /start resumes the paused bridge and opens a fresh runtime session

Permission Modes

  • default
    • approval policy: on-request
    • sandbox: workspace write
  • full-access
    • approval policy: never
    • sandbox: danger full access

The bridge accepts full_access, full-access, and full access.

Codex Manager Integration

Codex Manager is optional, but it unlocks:

  • /accounts
  • /switch_acc
  • quota visibility inside /status

Without Codex Manager, the core Telegram bridge still works.

Environment Variables

Required:

  • TELEGRAM_BOT_TOKEN

Optional:

  • CODEX_HOME
  • CODEX_TELEGRAM_BRIDGE_STATE_DIR
  • ENABLE_LOCAL_MIRROR
  • CODEX_MIRROR_HOST
  • CODEX_MIRROR_PORT
  • CODEX_MANAGER_STATE_PATH
  • CODEX_MANAGER_ELECTRON_USER_DATA_DIR
  • TELEGRAM_BRIDGE_ELECTRON_CLI

Wrapper defaults:

  • state is stored in .\.state
  • mirror auto-open is disabled with ENABLE_LOCAL_MIRROR=0

setup.cmd already handles TELEGRAM_BOT_TOKEN for most users.

Start on Windows Logon

Optional:

powershell -ExecutionPolicy Bypass -File .\scripts\register-startup-task.ps1

Git Setup

If you are preparing this folder as the public repository root:

git init
git branch -M main
git remote add origin https://github.com/chillinh/telegram-codex-bridge.git
git add .
git commit -m "Initial public release"
git push -u origin main

Release Tags

Recommended tag format:

  • v0.1.0
  • v0.1.1
  • v0.2.0

Typical release flow:

git add .
git commit -m "Release v0.1.0"
git push origin main
git tag v0.1.0
git push origin v0.1.0

If you publish GitHub Releases from tags, keep the tag name aligned with the version in package.json.

Security Notes

  • do not commit your Telegram bot token
  • do not commit .run/ logs
  • do not commit local auth or state files
  • Codex account payloads are not stored in this repo
  • only paired Telegram users can control the bridge

Safe Git Contents

This repo excludes:

  • node_modules/
  • .run/
  • .state/
  • *.log
  • .env*

Release Verification

Before publishing, verify:

  1. no token or private account data is hardcoded
  2. no local runtime logs or state files are included
  3. syntax still passes
node --check .\src\index.js
node --check .\src\console-client.js
node --check .\src\codex-manager-electron-helper.js

Huong Dan Tieng Viet

Muc tieu

Du an nay dung de dieu khien codex app-server tren may Windows bang Telegram, va co the mo them local mirror neu ban muon theo doi session dang chay.

Cach dung don gian cho nguoi dung

  1. Bam setup.cmd
  2. Nhap token Telegram bot
  3. De setup cai dependency va start bot
  4. Mo bot trong Telegram va gui /pair
  5. Bam approve-pair.cmd
  6. Dan ma pair vao cua so vua mo
  7. Gui /menu tren Telegram la dung duoc

Tat va bat lai bot

  • /stop: chi dung turn dang chay
  • /shutdown: tam dung toan bo bot
  • /start: bat lai bot sau khi pause

Mirror console va state mac dinh

  • Bot khong tu mo mirror console nua, tru khi ban set ENABLE_LOCAL_MIRROR=1
  • Neu can, ban co the chay tay .\scripts\launch-console.cmd
  • State mac dinh cua ban release duoc dat trong .\.state

Codex Manager co bat buoc khong

Khong bat buoc.

  • Bat buoc: Codex CLI
  • Khuyen dung them: Codex Manager

Neu co Codex Manager, nguoi dung se co them:

  • /accounts
  • /switch_acc
  • thong tin quota trong /status

Repo va tag release

Repo du kien:

  • https://github.com/chillinh/telegram-codex-bridge

Format tag nen dung:

  • v0.1.0
  • v0.1.1
  • v0.2.0

Flow release co the dung:

git add .
git commit -m "Release v0.1.0"
git push origin main
git tag v0.1.0
git push origin v0.1.0

Lenh hay dung

  • /status: xem model, mode, permission, workspace, quota
  • /accounts: xem danh sach account trong Codex Manager
  • /switch_acc 1: doi account theo thu tu
  • /permission default: quay ve che do can duyet
  • /permission full_access: chuyen sang full access
  • /set_workspace D:\project: doi thu muc lam viec
  • /restart: restart runtime va tao session moi
  • /shutdown: pause toan bo bot
  • /start: resume bot sau khi pause

Author

About

Telegram remote-control bridge for Codex CLI with Codex Manager integration and local mirror console on Windows

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages