codex-telegram

Telegram bot bridge for Codex CLI on Linux.

npm install

For a global install:

npm install -g codex-telegram
codex-telegram-install
codex-telegram

The npm package stores:

• config in ~/.config/codex-telegram/config.json
• runtime data in ~/.local/share/codex-telegram/
• env token in ~/.config/codex/codex-telegram.env

If you prefer not to install globally:

npx codex-telegram-install
npx codex-telegram

Features

• Send prompts to Codex from Telegram
• Streaming responses (JSONL events)
• Queueing (multiple messages)
• Per-chat session using Codex thread_id
• Saved session list with preview and manual session switching
• Automatic session compaction into a fresh thread when long-running context crosses configured thresholds

Setup (Ubuntu)

1) Install Node.js

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

2) Install Codex CLI

Install the Codex CLI in your environment and ensure codex is on PATH.

3) Configure the bot

cp config.example.json config.json
nano config.json

Fill in:

• telegram.token or TELEGRAM_BOT_TOKEN in the env file
• telegram.allowedUsers
• telegram.adminChatId
• codex.model (optional)
• codex.path (optional, if codex not on PATH)
• openai.adminKey (optional, for /costs)

Optional environment-based setup:

mkdir -p ~/.config/codex
cp .env.example ~/.config/codex/codex-telegram.env
nano ~/.config/codex/codex-telegram.env

By default the bot loads TELEGRAM_BOT_TOKEN from ~/.config/codex/codex-telegram.env before reading config.json. It also accepts the legacy fallback path ~/.config/opencode/codex-telegram.env for backward compatibility.

If you keep the token in the env file, config.json still needs telegram.allowedUsers and telegram.adminChatId so the bot knows who is allowed to use it.

Optional long-session controls in config.json:

• defaults.autoCompact.enabled - turn automatic compaction on or off
• defaults.autoCompact.maxTurns - compact after this many completed turns in one thread
• defaults.autoCompact.maxChars - compact when recorded prompt+response chars exceed this budget
• defaults.autoCompact.maxTokens - compact when cumulative Codex turn.completed.usage input+output tokens exceed this budget
• defaults.autoCompact.strategy - soft first asks Codex to summarize the current thread into carry-forward memory before rotating to a fresh session; hard skips that step

4) Install dependencies

npm install

5) Start

chmod +x start.sh
./start.sh

6) Systemd service (optional)

This template assumes the repo lives at ~/codex-telegram. If you keep the repo elsewhere, edit WorkingDirectory in codex-telegram.service before copying it.

mkdir -p ~/.config/codex
cp .env.example ~/.config/codex/codex-telegram.env
nano ~/.config/codex/codex-telegram.env
mkdir -p ~/.config/systemd/user
cp codex-telegram.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable codex-telegram
systemctl --user start codex-telegram

Check status and logs:

systemctl --user status codex-telegram --no-pager
journalctl --user -u codex-telegram -n 50 --no-pager

Fresh Machine Quick Start

For a clean Ubuntu machine, the shortest path is:

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @openai/codex
npm install
mkdir -p ~/.config/codex
cp .env.example ~/.config/codex/codex-telegram.env
nano ~/.config/codex/codex-telegram.env
cp config.example.json config.json
nano config.json
./start.sh

Installer Mode vs Manual Mode

You can set up codex-telegram in two ways:

• install.sh mode: Use the menu-driven installer when you want a step-by-step CLI wizard that asks for your Telegram token, your Telegram user ID, your admin chat ID, and optional Codex settings, then writes config.json and ~/.config/codex/codex-telegram.env for you.
• manual mode: Follow the commands in this README when you want explicit control over each step or when debugging an installation issue.

As a rule of thumb, use install.sh for first-time setup and manual mode when you need to inspect or customize the environment more closely.

Wizard flow:

./install.sh

Then choose:

1. 4 to install npm dependencies
2. 5 to run the setup wizard
3. 7 to start the bot

Development

Run tests locally:

npm test

Syntax check locally:

node --check bot.js
node --check telegram.js
node --check codex-client.js

CI Status

The repository includes a basic GitHub Actions workflow at .github/workflows/ci.yml.

Current CI scope:

• install dependencies with npm ci
• run the Node test suite with npm test

For a quick local health check without opening the installer menu:

./install.sh --check

If you later publish this repository to GitHub, you can add a workflow badge once the final repository URL is known.

Runtime Files

These files and folders are created locally while the bot runs and are ignored by Git:

• config.json
• sessions.json
• jobs.json
• long-term-memory.json
• uploads/
• bot.log
• .env

Troubleshooting

Bot does not start

• Check that codex is installed and available on PATH
• Check config.json or ~/.config/codex/codex-telegram.env
• Check that telegram.allowedUsers and telegram.adminChatId are set in config.json
• Run npm test first to confirm the local Node environment is healthy

Telegram bot does not respond

• Confirm TELEGRAM_BOT_TOKEN is valid
• Confirm your Telegram user ID is included in telegram.allowedUsers
• Check logs with:

journalctl --user -u codex-telegram -n 50 --no-pager

systemd service fails

• Reload the user daemon after copying the service file:

systemctl --user daemon-reload

• Re-check status:

systemctl --user status codex-telegram --no-pager

Config changes do not apply

• Restart the process after editing config or env values:

systemctl --user restart codex-telegram

• If you are not using systemd, stop the running process and start ./start.sh again

Commands

• /help show help
• /new clear conversation thread
• /sessions list saved sessions for this chat
• /session switch to a saved session, or rename one with rename
• /compress refresh a compact carry-forward summary for the current thread
• /model set model
• /thinking set reasoning effort
• /mode set execution mode (safe, workspace, danger)
• /system set system prompt
• /skill select skills for the current chat
• /memory show or manage session + long-term memory
• /mcpstatus show configured MCP servers
• /codex show Codex CLI status
• /costs show OpenAI costs (requires admin key)
• /usage show API usage & costs
• /disk check disk usage
• /cron manage background cron jobs
• /stop stop current response + clear queue
• /clear clear queued messages
• /restart restart bot
• /status show status

Memory

When codex-session-memory is selected in /skill, the bot keeps two layers of memory:

• thread memory: summary, pinned notes, and recent decisions for the current Codex thread
• long-term memory: chat-scoped notes stored in long-term-memory.json and retrieved by local search for future prompts

Useful commands:

/compress
/compress Preparing to split this task into a new thread.
/memory
/memory pin Use Cantonese / HK style unless I ask otherwise.
/memory remember Implement long-term memory before subagent orchestration.
/memory search subagent orchestration
/memory forget mem_abc123
/memory clear

Notes:

• /compress asks Codex to condense the current thread into carry-forward memory and shows the result
• /memory pin saves to the current thread and also persists the same note into long-term memory
• /memory clear only clears the current thread memory
• /memory forget removes long-term memory for the current chat only

Background jobs

Background jobs run in separate Codex sessions, so they do not reuse the foreground chat thread or queue.

Examples:

/cron
/cron add
/cron add Daily report | daily:09:30 | Summarize open work, blockers, and the next priority.
/cron run job_abc123
/cron pause job_abc123
/cron resume job_abc123
/cron delete job_abc123

Wizard flow:

• /cron add
• Choose One Time or Recurring
• Send a natural-language schedule such as in 10m, tomorrow 09:30, every 2h, or daily 09:30
• Send the job prompt in natural language

Supported schedule formats:

• every:5m
• every:1h
• every:1d
• daily:09:30