{"id":49792367,"url":"https://github.com/incursa/codex-telegram","last_synced_at":"2026-05-24T07:01:36.777Z","repository":{"id":356122458,"uuid":"1227759639","full_name":"incursa/codex-telegram","owner":"incursa","description":"Telegram bot for controlling a local Codex CLI session from an allowlisted chat.","archived":false,"fork":false,"pushed_at":"2026-05-22T16:59:31.000Z","size":5268,"stargazers_count":3,"open_issues_count":8,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T19:55:24.394Z","etag":null,"topics":["cli","codex","dotnet","local-first","openai","telegram-bot"],"latest_commit_sha":null,"homepage":"https://github.com/incursa/codex-telegram/releases/latest","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/incursa.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-03T06:00:40.000Z","updated_at":"2026-05-22T17:01:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/incursa/codex-telegram","commit_stats":null,"previous_names":["incursa/codex-telegram"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/incursa/codex-telegram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/incursa%2Fcodex-telegram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/incursa%2Fcodex-telegram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/incursa%2Fcodex-telegram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/incursa%2Fcodex-telegram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/incursa","download_url":"https://codeload.github.com/incursa/codex-telegram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/incursa%2Fcodex-telegram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33424573,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","codex","dotnet","local-first","openai","telegram-bot"],"created_at":"2026-05-12T06:03:47.723Z","updated_at":"2026-05-24T07:01:36.769Z","avatar_url":"https://github.com/incursa.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Incursa Codex Telegram\n\nIncursa 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.\n\nUse it when you want to start, steer, and inspect Codex work from your phone without exposing your whole machine to Telegram users.\n\n## Demo\n\nWatch a two-minute private-chat demo showing a local Codex session controlled from Telegram with project selection, text prompts, and voice input.\n\n[![Watch the Codex Telegram demo](docs/assets/codex-telegram-demo-thumbnail.png)](https://github.com/incursa/codex-telegram/raw/main/docs/assets/codex-telegram-demo.mp4)\n\nFor the available Telegram buttons and menus, see the [menus and button reference](docs/menus.md).\n\n## Download\n\nDownload the latest release binary for your operating system:\n\n| Platform | Download | Checksum |\n| --- | --- | --- |\n| Windows x64 | [codex-telegram-win-x64.exe](https://github.com/incursa/codex-telegram/releases/latest/download/codex-telegram-win-x64.exe) | [sha256](https://github.com/incursa/codex-telegram/releases/latest/download/codex-telegram-win-x64.exe.sha256) |\n| Linux x64 | [codex-telegram-linux-x64](https://github.com/incursa/codex-telegram/releases/latest/download/codex-telegram-linux-x64) | [sha256](https://github.com/incursa/codex-telegram/releases/latest/download/codex-telegram-linux-x64.sha256) |\n| macOS arm64 | [codex-telegram-osx-arm64](https://github.com/incursa/codex-telegram/releases/latest/download/codex-telegram-osx-arm64) | [sha256](https://github.com/incursa/codex-telegram/releases/latest/download/codex-telegram-osx-arm64.sha256) |\n\nAll releases are listed at [GitHub Releases](https://github.com/incursa/codex-telegram/releases).\n\n## What You Need\n\nBefore starting, have these ready:\n\n1. A Telegram account.\n2. A Telegram bot token from `@BotFather`.\n3. A local Codex CLI installation that already works in a terminal.\n4. At least one local repository or workspace directory you want Codex to use.\n5. Optional: an OpenAI API key for voice-note transcription. Install `ffmpeg` only if Telegram audio must be transcoded; Telegram voice notes commonly need it.\n\nThis 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.\n\nFor Codex CLI setup, use OpenAI's official [Codex CLI docs](https://developers.openai.com/codex/cli).\n\n## Quick Start\n\nStart by creating a Telegram bot, then follow the complete setup path for your operating system.\n\n### Create A Telegram Bot\n\nIn Telegram:\n\n1. Open a chat with `@BotFather`.\n2. Send `/newbot`.\n3. Choose a display name.\n4. Choose a username ending in `bot`.\n5. Copy the bot token.\n\nKeep the token private. Anyone with the token can control the bot account.\n\nRecommended BotFather settings for a first private-chat release:\n\n1. Use `/setdescription` and `/setabouttext` to explain that this bot controls a local Codex installation.\n2. Keep group joins disabled unless you intentionally want group support.\n3. Keep privacy mode enabled unless you intentionally need ordinary group text routed to Codex.\n4. Add commands later after the private-chat flow works.\n\nCopy-paste BotFather text, command lists, and privacy recommendations are in [BotFather setup](docs/botfather.md).\n\nBotFather 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.\n\n### Windows\n\nUse this path if the bot will run on Windows x64.\n\n1. Download `codex-telegram-win-x64.exe` and `codex-telegram-win-x64.exe.sha256` from the [latest release](https://github.com/incursa/codex-telegram/releases/latest).\n2. Optional but recommended: verify the checksum before renaming or moving the file.\n\n```powershell\nGet-FileHash .\\codex-telegram-win-x64.exe -Algorithm SHA256\nGet-Content .\\codex-telegram-win-x64.exe.sha256\n```\n\n3. Put the binary in a stable folder.\n\n```powershell\nNew-Item -ItemType Directory -Force C:\\tools\\codex-telegram | Out-Null\nMove-Item .\\codex-telegram-win-x64.exe C:\\tools\\codex-telegram\\codex-telegram.exe\nSet-Location C:\\tools\\codex-telegram\n```\n\n4. Confirm Codex works locally before involving Telegram.\n\n```powershell\ncodex --version\ncodex\n```\n\n5. Start the setup menu from the app folder.\n\n```powershell\n.\\codex-telegram.exe\n```\n\n6. Complete the first-run wizard.\n\nUse these values as a starting point:\n\n```text\nTelegram bot token: \u003ctoken from BotFather\u003e\nTelegram polling: enabled\nAdmin user ID: let the wizard capture it by sending one private Telegram message to the bot\nCodex executable path: leave blank if codex is on PATH, otherwise set the full codex.exe path\nWorkspace root: C:\\src\nDefault working directory: C:\\src\\your-repo\nOpenAI transcription: only if you want voice notes\nLocal data root: leave blank unless you need a custom state folder\n```\n\nThe 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.\n\n7. Start normal operation with the menu skipped.\n\n```powershell\n.\\codex-telegram.exe --run\n```\n\nKeep that terminal open, or run the app under your preferred Windows service manager.\n\n8. In the private Telegram chat, run the first private Codex session.\n\n```text\n/doctor\n/projects\n/project add C:\\src\\your-repo\n/new release-demo\nSummarize this repository and tell me the next safest setup check to run.\n/tail\n```\n\nAt this point you have a working private Telegram chat connected to a local Codex session.\n\n### Linux\n\nUse this path if the bot will run on Linux x64.\n\n1. Download `codex-telegram-linux-x64` and `codex-telegram-linux-x64.sha256` from the [latest release](https://github.com/incursa/codex-telegram/releases/latest).\n2. Or download both files directly with `curl`.\n\n```bash\ncurl -fL -o codex-telegram-linux-x64 https://github.com/incursa/codex-telegram/releases/latest/download/codex-telegram-linux-x64\ncurl -fL -o codex-telegram-linux-x64.sha256 https://github.com/incursa/codex-telegram/releases/latest/download/codex-telegram-linux-x64.sha256\n```\n\n3. Optional but recommended: verify the checksum before renaming or moving the file.\n\n```bash\nshasum -a 256 -c ./codex-telegram-linux-x64.sha256\n```\n\n4. Put the binary in a stable folder and mark it executable.\n\n```bash\nmkdir -p ~/tools/codex-telegram\nmv ./codex-telegram-linux-x64 ~/tools/codex-telegram/codex-telegram\nchmod +x ~/tools/codex-telegram/codex-telegram\ncd ~/tools/codex-telegram\n```\n\n5. Confirm Codex works locally before involving Telegram.\n\n```bash\ncodex --version\ncodex\n```\n\n6. Start the setup menu from the app folder.\n\n```bash\n./codex-telegram\n```\n\n7. Complete the first-run wizard.\n\nUse these values as a starting point:\n\n```text\nTelegram bot token: \u003ctoken from BotFather\u003e\nTelegram polling: enabled\nAdmin user ID: let the wizard capture it by sending one private Telegram message to the bot\nCodex executable path: leave blank if codex is on PATH, otherwise set the full codex path\nWorkspace root: /home/you/src\nDefault working directory: /home/you/src/your-repo\nOpenAI transcription: only if you want voice notes\nLocal data root: leave blank unless you need a custom state folder\n```\n\nThe 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.\n\n8. Start normal operation with the menu skipped.\n\n```bash\n./codex-telegram --run\n```\n\nKeep that terminal open, or run the app under systemd, tmux, screen, or another process supervisor.\n\n9. In the private Telegram chat, run the first private Codex session.\n\n```text\n/doctor\n/projects\n/project add /home/you/src/your-repo\n/new release-demo\nSummarize this repository and tell me the next safest setup check to run.\n/tail\n```\n\nAt this point you have a working private Telegram chat connected to a local Codex session.\n\n### macOS\n\nUse this path if the bot will run on Apple Silicon macOS.\n\n1. Download `codex-telegram-osx-arm64` and `codex-telegram-osx-arm64.sha256` from the [latest release](https://github.com/incursa/codex-telegram/releases/latest).\n2. Or download both files directly with `curl`.\n\n```bash\ncurl -fL -o codex-telegram-osx-arm64 https://github.com/incursa/codex-telegram/releases/latest/download/codex-telegram-osx-arm64\ncurl -fL -o codex-telegram-osx-arm64.sha256 https://github.com/incursa/codex-telegram/releases/latest/download/codex-telegram-osx-arm64.sha256\n```\n\n3. Optional but recommended: verify the checksum before renaming or moving the file.\n\n```bash\nshasum -a 256 -c ./codex-telegram-osx-arm64.sha256\n```\n\n4. Put the binary in a stable folder and mark it executable.\n\n```bash\nmkdir -p ~/tools/codex-telegram\nmv ./codex-telegram-osx-arm64 ~/tools/codex-telegram/codex-telegram\nchmod +x ~/tools/codex-telegram/codex-telegram\ncd ~/tools/codex-telegram\n```\n\n5. 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.\n\n```bash\nxattr -d com.apple.quarantine ~/tools/codex-telegram/codex-telegram\n```\n\n6. Confirm Codex works locally before involving Telegram.\n\n```bash\ncodex --version\ncodex\n```\n\n7. Start the setup menu from the app folder.\n\n```bash\n./codex-telegram\n```\n\n8. Complete the first-run wizard.\n\nUse these values as a starting point:\n\n```text\nTelegram bot token: \u003ctoken from BotFather\u003e\nTelegram polling: enabled\nAdmin user ID: let the wizard capture it by sending one private Telegram message to the bot\nCodex executable path: leave blank if codex is on PATH, otherwise set the full codex path\nWorkspace root: /Users/you/src\nDefault working directory: /Users/you/src/your-repo\nOpenAI transcription: only if you want voice notes\nLocal data root: leave blank unless you need a custom state folder\n```\n\nThe 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.\n\n9. Start normal operation with the menu skipped.\n\n```bash\n./codex-telegram --run\n```\n\nKeep that terminal open, or run the app under launchd, tmux, screen, or another process supervisor.\n\n10. In the private Telegram chat, run the first private Codex session.\n\n```text\n/doctor\n/projects\n/project add /Users/you/src/your-repo\n/new release-demo\nSummarize this repository and tell me the next safest setup check to run.\n/tail\n```\n\nAt this point you have a working private Telegram chat connected to a local Codex session.\n\n## Voice Notes\n\nVoice 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.\n\nVoice note requirements:\n\n1. `OpenAI:ApiKey` or `OPENAI_API_KEY`.\n2. A transcription-capable `OpenAI:Model`.\n3. `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.\n\nIf `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.\n\nSuggested first voice test:\n\n```text\nPlease review the current project and tell me the three most important setup risks. Keep it concise and do not edit files.\n```\n\nAfter a successful test, you should see the transcription in Telegram before the Codex response starts.\n\n## Day-To-Day Commands\n\n| Command | Use |\n| --- | --- |\n| `/doctor` | Explain authorization, routing, active project/session, workspace roots, queue state, and next action. |\n| `/help` | Show the built-in command summary. |\n| `/whoami` | Show Telegram user, chat, and topic IDs for setup and troubleshooting. |\n| `/version` | Show the running app version. |\n| `/trust` | Trust the current group or forum chat for allowlisted users. |\n| `/projects` | List known local project directories. |\n| `/project add \u003cpath\u003e` | Add and select a repository or workspace. |\n| `/project current` | Confirm the active project for this Telegram conversation. |\n| `/new [name]` | Create and select a fresh Codex session; omit the name to auto-generate one from the active project. |\n| `/sessions` | Show active and Telegram-managed sessions. |\n| `/sessions all [count]` | Show older Codex history. |\n| `/use \u003csessionId\u003e` | Resume an existing session. |\n| `/send \u003ctext\u003e` | Explicitly send text when privacy mode or chat type prevents normal auto-routing. |\n| `/steer \u003ctext\u003e` | Add guidance to a currently active turn. |\n| `/queue` | View queued prompts for the conversation, then edit, delete, or send one now. |\n| `/model` | Show or change the active session model. |\n| `/thinking` | Show or change reasoning effort. |\n| `/goal` | Show or change the active session goal. |\n| `/status` | Show active session status, including compact Codex usage when available. |\n| `/usage` | Show five-hour and weekly Codex usage, with reset times. |\n| `/tail [lines]` | Show recent output and keep following the session; defaults to 40 lines. |\n| `/outbound` | Inspect delayed or batched Telegram output. |\n| `/stop` | Gracefully stop a session. |\n| `/restart confirm` | Show standalone-process restart guidance. |\n| `/topic ...` | Manage forum-topic sessions in allowed supergroups. |\n\nFor a fuller operator guide, see [docs/usage.md](docs/usage.md).\nFor every command, parameter, and expected behavior, see [docs/command-reference.md](docs/command-reference.md).\n\n## How Output Delivery Works\n\nTelegram output is rate-limited and batched so active Codex sessions do not flood your chat.\n\nPractical rules:\n\n1. Use `/tail` before assuming Telegram scrollback contains the full transcript.\n2. Use `/outbound` if messages seem delayed.\n3. Use `/usage` when you need current five-hour and weekly Codex usage percentages and reset times.\n4. Batched messages are concatenated with simple spacing and preserve multi-line content, including numbered lists and headings.\n5. If the local outbound buffer is compacted, the bot sends an explicit compaction notice.\n6. Terminal turn events are tracked internally; the bot no longer emits a standalone completion marker into the chat.\n\n## Local State And Safety\n\nThe app stores local state under `CodexTelegram:Workspace:DataRoot`. By default, that is the user's application data folder.\n\nState includes:\n\n1. `projects.json`\n2. `telegram-state.json`\n3. Per-thread manifests\n\nSecrets 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.\n\nSecurity rules:\n\n1. Keep `TelegramBot:AllowedUserIds` narrow.\n2. Keep `TelegramBot:AllowedChatIds` empty unless you intentionally want config-managed group or forum-topic access.\n3. Set explicit workspace roots and a default working directory before enabling polling.\n4. Review Codex sandbox and approval settings before exposing sensitive repositories.\n5. Rotate the BotFather token if it is exposed.\n\n## Supported Modes\n\nPrivate chat is the recommended first setup path. Trusted groups and forum topics are also supported conversation scopes.\n\nGroups and forum topics require:\n\n1. An allowed Telegram user.\n2. A trusted group chat, either from `TelegramBot:AllowedChatIds` or `/trust` sent in that chat by an allowlisted user.\n3. BotFather privacy settings that match the desired behavior.\n4. Topic-management rights if the bot should create forum topics.\n\nStart 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.\n\n## Support And Security\n\nFor general open-source project questions, contact oss@incursa.com.\n\nFor 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.\n\n## More Documentation\n\nUser and operator docs:\n\n- [Getting started guide](docs/getting-started.md)\n- [Day-to-day usage](docs/usage.md)\n- [Operations](docs/operations.md)\n- [BotFather setup](docs/botfather.md)\n- [Command reference](docs/command-reference.md)\n- [Menus and button reference](docs/menus.md)\n- [Security](SECURITY.md)\n\nDeveloper and maintainer docs:\n\n- [Development guide](docs/development.md)\n- [Contributing](CONTRIBUTING.md)\n- [Code of conduct](CODE_OF_CONDUCT.md)\n- [Testing and quality](docs/testing.md)\n- [Manual Telegram test plan](docs/manual-test-plan.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fincursa%2Fcodex-telegram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fincursa%2Fcodex-telegram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fincursa%2Fcodex-telegram/lists"}