GitHub - incursa/codex-telegram: Telegram bot for controlling a local Codex CLI session from an allowlisted chat.

Incursa Codex Telegram lets you talk to a local Codex CLI session from a private Telegram chat. It runs on your own machine, stores state locally, and only accepts messages from allowlisted Telegram users.

Use it when you want to start, steer, and inspect Codex work from your phone without exposing your whole machine to Telegram users.

Demo

Watch a two-minute private-chat demo showing a local Codex session controlled from Telegram with project selection, text prompts, and voice input.

For the available Telegram buttons and menus, see the menus and button reference.

Runtime Modes

The service has a small set of operating modes:

1. Start it with no arguments in an interactive terminal to open the bootstrap/admin menu.
2. Start it with --run to skip the menu and run the hosted services directly.
3. Start it with --menu to force the bootstrap/admin menu.
4. Use private chat first, then trusted group roots or forum topics only after the private flow works.
5. Use docs/usage.md for the user-facing output modes: Compact, Verbose, LiveCard, and FinalOnly.

Configuration And Secrets

The main configuration file is src/Incursa.Codex.Telegram/appsettings.json. Keep local values in one of these places:

1. appsettings.Local.json
2. User secrets
3. Environment variables
4. An operator-managed secret store

Keep these out of version control:

1. Telegram bot tokens.
2. OpenAI API keys.
3. Local Codex auth state.
4. appsettings.Local.json.
5. Local debug traces and private transcripts.

Repository Layout

The main folders and files are:

1. src/Incursa.Codex.Telegram: the console host, Telegram routing, Codex integration, configuration, and runtime services.
2. tests/Incursa.Codex.Telegram.Tests: unit and integration-style tests for commands, state, queueing, output, and Telegram behavior.
3. docs/: source-authored operator, maintainer, and command documentation.
4. scripts/: local release, publish, fuzz, mutation, and secret-scan scripts.
5. specs/: repository-native requirements and architecture notes.
6. fuzz/corpus/: checked-in Telegram fuzz seeds.
7. docs.site.json and .github/workflows/sync-docs.yml: the docs mirror manifest and sync workflow.

Download

Download the latest release binary for your operating system:

All releases are listed at GitHub Releases.

What You Need

Before starting, have these ready:

1. A Telegram account.
2. A Telegram bot token from @BotFather.
3. A local Codex CLI installation that already works in a terminal.
4. At least one local repository or workspace directory you want Codex to use.
5. Optional: an OpenAI API key for voice-note transcription. Install ffmpeg only if Telegram audio must be transcoded; Telegram voice notes commonly need it.

This app does not bundle Codex, Telegram credentials, or OpenAI credentials. If you use voice notes, any required audio transcoder must already exist on the machine running the bot.

For Codex CLI setup, use OpenAI's official Codex CLI docs.

Quick Start

Start by creating a Telegram bot, then follow the complete setup path for your operating system.

Create A Telegram Bot

In Telegram:

1. Open a chat with @BotFather.
2. Send /newbot.
3. Choose a display name.
4. Choose a username ending in bot.
5. Copy the bot token.

Keep the token private. Anyone with the token can control the bot account.

Recommended BotFather settings for a first private-chat release:

1. Use /setdescription and /setabouttext to explain that this bot controls a local Codex installation.
2. Keep group joins disabled unless you intentionally want group support.
3. Keep privacy mode enabled unless you intentionally need ordinary group text routed to Codex.
4. Add commands later after the private-chat flow works.

Copy-paste BotFather text, command lists, and privacy recommendations are in BotFather setup.

BotFather gives you the bot token, but it cannot give you your personal Telegram user ID. On first run, Codex Telegram can validate the bot token, show a random setup code in the terminal, wait for one private message containing that code, and save your user ID automatically.

Windows

Use this path if the bot will run on Windows x64.

1. Download codex-telegram-win-x64.exe and codex-telegram-win-x64.exe.sha256 from the latest release.
2. Optional but recommended: verify the checksum before renaming or moving the file.

Get-FileHash .\codex-telegram-win-x64.exe -Algorithm SHA256
Get-Content .\codex-telegram-win-x64.exe.sha256

3. Put the binary in a stable folder.

New-Item -ItemType Directory -Force C:\tools\codex-telegram | Out-Null
Move-Item .\codex-telegram-win-x64.exe C:\tools\codex-telegram\codex-telegram.exe
Set-Location C:\tools\codex-telegram

4. Confirm Codex works locally before involving Telegram.

5. Start the setup menu from the app folder.

6. Complete the first-run wizard.

Use these values as a starting point:

Telegram bot token: <token from BotFather>
Telegram polling: enabled
Admin user ID: let the wizard capture it by sending one private Telegram message to the bot
Codex executable path: leave blank if codex is on PATH, otherwise set the full codex.exe path
Workspace root: C:\src
Default working directory: C:\src\your-repo
OpenAI transcription: only if you want voice notes
Local data root: leave blank unless you need a custom state folder

The app writes appsettings.Local.json beside the executable by default. Keep that file local and untracked. If the executable-local file is missing and your launch directory has appsettings.Local.json, the app uses the launch-directory file.

7. Start normal operation with the menu skipped.

.\codex-telegram.exe --run

Keep that terminal open, or run the app under your preferred Windows service manager.

8. In the private Telegram chat, run the first private Codex session.

/doctor
/projects
/project add C:\src\your-repo
/new release-demo
Summarize this repository and tell me the next safest setup check to run.
/tail

At this point you have a working private Telegram chat connected to a local Codex session.

Linux

Use this path if the bot will run on Linux x64.

1. Download codex-telegram-linux-x64 and codex-telegram-linux-x64.sha256 from the latest release.
2. Or download both files directly with curl.

curl -fL -o codex-telegram-linux-x64 https://github.com/incursa/codex-telegram/releases/latest/download/codex-telegram-linux-x64
curl -fL -o codex-telegram-linux-x64.sha256 https://github.com/incursa/codex-telegram/releases/latest/download/codex-telegram-linux-x64.sha256

3. Optional but recommended: verify the checksum before renaming or moving the file.

shasum -a 256 -c ./codex-telegram-linux-x64.sha256

4. Put the binary in a stable folder and mark it executable.

mkdir -p ~/tools/codex-telegram
mv ./codex-telegram-linux-x64 ~/tools/codex-telegram/codex-telegram
chmod +x ~/tools/codex-telegram/codex-telegram
cd ~/tools/codex-telegram

5. Confirm Codex works locally before involving Telegram.

6. Start the setup menu from the app folder.

7. Complete the first-run wizard.

Use these values as a starting point:

Telegram bot token: <token from BotFather>
Telegram polling: enabled
Admin user ID: let the wizard capture it by sending one private Telegram message to the bot
Codex executable path: leave blank if codex is on PATH, otherwise set the full codex path
Workspace root: /home/you/src
Default working directory: /home/you/src/your-repo
OpenAI transcription: only if you want voice notes
Local data root: leave blank unless you need a custom state folder

The app writes appsettings.Local.json beside the executable by default. Keep that file local and untracked. If the executable-local file is missing and your launch directory has appsettings.Local.json, the app uses the launch-directory file.

8. Start normal operation with the menu skipped.

Keep that terminal open, or run the app under systemd, tmux, screen, or another process supervisor.

9. In the private Telegram chat, run the first private Codex session.

/doctor
/projects
/project add /home/you/src/your-repo
/new release-demo
Summarize this repository and tell me the next safest setup check to run.
/tail

At this point you have a working private Telegram chat connected to a local Codex session.

macOS

Use this path if the bot will run on Apple Silicon macOS.

1. Download codex-telegram-osx-arm64 and codex-telegram-osx-arm64.sha256 from the latest release.
2. Or download both files directly with curl.

curl -fL -o codex-telegram-osx-arm64 https://github.com/incursa/codex-telegram/releases/latest/download/codex-telegram-osx-arm64
curl -fL -o codex-telegram-osx-arm64.sha256 https://github.com/incursa/codex-telegram/releases/latest/download/codex-telegram-osx-arm64.sha256

3. Optional but recommended: verify the checksum before renaming or moving the file.

shasum -a 256 -c ./codex-telegram-osx-arm64.sha256

4. Put the binary in a stable folder and mark it executable.

mkdir -p ~/tools/codex-telegram
mv ./codex-telegram-osx-arm64 ~/tools/codex-telegram/codex-telegram
chmod +x ~/tools/codex-telegram/codex-telegram
cd ~/tools/codex-telegram

5. If macOS blocks the binary because it was downloaded from the internet, verify the checksum first. If you trust the release, remove the quarantine attribute.

xattr -d com.apple.quarantine ~/tools/codex-telegram/codex-telegram

6. Confirm Codex works locally before involving Telegram.

7. Start the setup menu from the app folder.

8. Complete the first-run wizard.

Use these values as a starting point:

Telegram bot token: <token from BotFather>
Telegram polling: enabled
Admin user ID: let the wizard capture it by sending one private Telegram message to the bot
Codex executable path: leave blank if codex is on PATH, otherwise set the full codex path
Workspace root: /Users/you/src
Default working directory: /Users/you/src/your-repo
OpenAI transcription: only if you want voice notes
Local data root: leave blank unless you need a custom state folder

The app writes appsettings.Local.json beside the executable by default. Keep that file local and untracked. If the executable-local file is missing and your launch directory has appsettings.Local.json, the app uses the launch-directory file.

9. Start normal operation with the menu skipped.

Keep that terminal open, or run the app under launchd, tmux, screen, or another process supervisor.

10. In the private Telegram chat, run the first private Codex session.

/doctor
/projects
/project add /Users/you/src/your-repo
/new release-demo
Summarize this repository and tell me the next safest setup check to run.
/tail

At this point you have a working private Telegram chat connected to a local Codex session.

Voice Notes

Voice notes are optional. The bot downloads Telegram audio, transcribes it with OpenAI, shows the transcript, and sends only the transcribed text to the active Codex session. Codex does not receive raw Telegram audio.

Voice note requirements:

1. OpenAI:ApiKey or OPENAI_API_KEY.
2. A transcription-capable OpenAI:Model.
3. ffmpeg only when the downloaded audio is not in a format OpenAI accepts directly. Telegram voice notes commonly arrive as OGG/OPUS, so install ffmpeg or configure OpenAI:FfmpegPath for reliable voice-note support.

If ffmpeg is missing when a voice note needs conversion, the bot leaves the Codex session untouched and replies with setup guidance instead of failing silently.

Suggested first voice test:

Please review the current project and tell me the three most important setup risks. Keep it concise and do not edit files.

After a successful test, you should see the transcription in Telegram before the Codex response starts.

Day-To-Day Commands

For a fuller operator guide, see docs/usage.md. For every command, parameter, and expected behavior, see docs/command-reference.md.

How Output Delivery Works

Telegram output is rate-limited and batched so active Codex sessions do not flood your chat.

Practical rules:

1. Use /tail before assuming Telegram scrollback contains the full transcript.
2. Use /outbound if messages seem delayed.
3. Use /usage when you need current five-hour and weekly Codex usage percentages and reset times.
4. Batched messages are concatenated with simple spacing and preserve multi-line content, including numbered lists and headings.
5. If the local outbound buffer is compacted, the bot sends an explicit compaction notice.
6. Terminal turn events are tracked internally; the bot no longer emits a standalone completion marker into the chat.

Local State And Safety

The app stores local state under CodexTelegram:Workspace:DataRoot. By default, that is the user's application data folder.

State includes:

1. projects.json
2. telegram-state.json
3. Per-thread manifests

Secrets should stay in appsettings.Local.json, user secrets, environment variables, or another secret store. Secrets are not supposed to be written to the state files.

Security rules:

1. Keep TelegramBot:AllowedUserIds narrow.
2. Keep TelegramBot:AllowedChatIds empty unless you intentionally want config-managed group or forum-topic access.
3. Set explicit workspace roots and a default working directory before enabling polling.
4. Review Codex sandbox and approval settings before exposing sensitive repositories.
5. Rotate the BotFather token if it is exposed.

Supported Modes

Private chat is the recommended first setup path. Trusted groups and forum topics are also supported conversation scopes.

Groups and forum topics require:

1. An allowed Telegram user.
2. A trusted group chat, either from TelegramBot:AllowedChatIds or /trust sent in that chat by an allowlisted user.
3. BotFather privacy settings that match the desired behavior.
4. Topic-management rights if the bot should create forum topics.

Start privately first. Then use a trusted group root as a single project/session lane, or use forum topics when one group needs multiple independent sessions.

Local Validation

Run these commands from the repository root:

dotnet restore CodexTelegram.slnx
dotnet build CodexTelegram.slnx -c Release -m:1 --no-restore
dotnet test tests\Incursa.Codex.Telegram.Tests\Incursa.Codex.Telegram.Tests.csproj -c Release --no-build --no-restore -m:1
.\scripts\Test-ReleaseReadiness.ps1 -Runtime win-x64 -SkipPublish
git diff --check

Release And Versioning

The repository publishes self-contained release binaries through scripts\Publish.ps1 and .github/workflows/publish.yml.

Release tags that start with v produce GitHub Releases with Windows x64, Linux x64, and macOS arm64 assets, plus SHA-256 checksum files and a copied LICENSE.txt.

Before a public release, run the repo-native release gate and the live Telegram checklist:

.\scripts\Test-ReleaseReadiness.ps1 -Runtime win-x64

Then follow docs/manual-test-plan.md against the exact commit or published asset being released.

Documentation Ownership

The docs/ tree is source-authored documentation.

The docs sync workflow uses docs.site.json and .github/workflows/sync-docs.yml to mirror that tree into incursa-docs/src/content/docs/open-source/codex-telegram/. Edit the source files in this repository, not the mirrored copies in incursa-docs.

Known Gaps

1. Live Telegram behavior still needs a real bot account and real credentials for validation.
2. Group and forum-topic support is supported but higher risk than private chat; validate it separately before calling a release ready.
3. Voice-note support depends on OpenAI and, when transcoding is needed, ffmpeg.
4. The mirrored documentation tree is generated from this repository and should not be edited directly in the central docs repo.

Support And Security

For general open-source project questions, contact oss@incursa.com.

For security issues, use GitHub private vulnerability reporting when it is enabled for this repository. If that is unavailable, contact security@incursa.com. Do not include secrets, private transcripts, exploit details, or local credential paths in public issues.

More Documentation

User and operator docs:

• Getting started guide
• Documentation index
• Day-to-day usage
• Operations
• BotFather setup
• Command reference
• Menus and button reference
• Security

Developer and maintainer docs:

• Development guide
• Maintainer readiness
• Contributing
• Code of conduct
• Testing and quality
• Manual Telegram test plan