{"id":49832999,"url":"https://github.com/yashau/dexgram","last_synced_at":"2026-05-23T00:12:18.108Z","repository":{"id":357466269,"uuid":"1237034933","full_name":"yashau/dexgram","owner":"yashau","description":"Lightweight Telegram bridge for Codex on Windows","archived":false,"fork":false,"pushed_at":"2026-05-17T21:22:20.000Z","size":334,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T01:03:22.576Z","etag":null,"topics":["agent","ai","codex","codex-cli","golang","telegram","windows"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yashau.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-12T20:14:19.000Z","updated_at":"2026-05-17T21:17:50.000Z","dependencies_parsed_at":"2026-05-18T01:01:03.569Z","dependency_job_id":null,"html_url":"https://github.com/yashau/dexgram","commit_stats":null,"previous_names":["yashau/dexgram"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/yashau/dexgram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yashau%2Fdexgram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yashau%2Fdexgram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yashau%2Fdexgram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yashau%2Fdexgram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yashau","download_url":"https://codeload.github.com/yashau/dexgram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yashau%2Fdexgram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33198811,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-18T09:27:30.708Z","status":"online","status_checked_at":"2026-05-19T02:00:06.763Z","response_time":58,"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":["agent","ai","codex","codex-cli","golang","telegram","windows"],"created_at":"2026-05-13T22:01:19.412Z","updated_at":"2026-05-23T00:12:18.101Z","avatar_url":"https://github.com/yashau.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dexgram\n\n[![CI](https://img.shields.io/github/actions/workflow/status/yashau/dexgram/ci.yml?branch=main\u0026style=for-the-badge\u0026label=CI)](https://github.com/yashau/dexgram/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/yashau/dexgram?style=for-the-badge)](https://github.com/yashau/dexgram/releases)\n[![License](https://img.shields.io/github/license/yashau/dexgram?style=for-the-badge)](LICENSE)\n![Windows Only](https://img.shields.io/badge/Windows-Only-0078D4?style=for-the-badge\u0026logo=windows11\u0026logoColor=white)\n[![Go](https://img.shields.io/badge/Go-1.26-00ADD8?style=for-the-badge\u0026logo=go\u0026logoColor=white)](https://go.dev/)\n\nCodex, wired straight into Telegram topics.\n\nDexgram is a Windows-only bridge that lets a Telegram bot drive real Codex\nsessions. Each Telegram topic can become a resumable Codex thread, a\nproject-bound workspace, a side quest fork, or an attached session you already\nstarted in Codex.\n\nIt ships as a native Windows binary. No local web app to babysit, no Node\nruntime, no npm install, no surprise dependency pile just to send a prompt from\nyour phone.\n\nIt does not fake this by scraping a terminal. Dexgram talks to the Codex\napp-server, so Telegram gets the good stuff: assistant text, live run logs, tool\nactivity, file edits, approvals, input requests, queued-message controls, and\nfinal answers. Your phone becomes a command deck for the Codex sessions already\nliving on your Windows machine.\n\n## Why Dexgram Hits Different\n\n- **One native binary**: no Node runtime, no npm install, no local dashboard\n  stack. Download `dexgram.exe`, configure your bot, and run it beside Codex.\n- **Telegram is the interface**: stable push notifications, threaded chats,\n  groups, DMs, search, files, photos, and mobile apps are already there.\n  Dexgram only has to be the bridge.\n- **No network gymnastics**: remote coding tools often make you care about\n  line of sight, VPNs, Tailscale, port forwarding, relay servers, or a big\n  custom dashboard. Telegram already solved reliable mobile messaging.\n- **Still useful after Codex mobile**: Codex is now in preview inside the\n  ChatGPT mobile app, but it still depends on connected hosts and early reports\n  make the experience sound rough around the edges. Dexgram stays deliberately\n  simple: Telegram topic in, Codex session out.\n- **Topic-native Codex**: one Telegram topic maps to one Codex thread, with\n  `/sessions [query]` for attaching existing sessions, `/new` for fresh chats,\n  `/project` for project-bound work, and `/sync [limit]` for bounded history\n  sync.\n- **Two-way transcript sync**: Desktop-origin replies show up in Telegram in\n  near real time, with the Desktop prompt quoted above the bot reply. Telegram\n  prompts are also appended back into the Codex Desktop transcript as\n  `Telegram: ...` entries. Caveat: Codex Desktop only shows those inserted\n  Telegram entries after the desktop thread is reloaded or Codex is restarted;\n  see Existing Sessions below.\n- **Real side quests**: `/side` and `/btw` create native Codex thread forks in\n  fresh Telegram topics, keeping the same project and cwd while the tangent runs\n  independently.\n- **Live, controllable runs**: Telegram mirrors assistant text, run logs, tool\n  activity, file edits, final answers, approvals, and input prompts. Messages\n  sent while Codex is busy queue locally with steer/delete controls.\n- **Local context without drama**: attachments, local file links, goals, Plan\n  Mode, model selection, reasoning effort, hot reload, pairing codes, and the\n  Windows login task all stay inside the small bridge.\n\n## Windows Only\n\nDexgram is intentionally Windows-only. Codex is local, the app-server is\nlocal, and the bridge is happiest when it can live beside them.\n\nService mode uses a current-user Task Scheduler login task, falling back to the\nper-user Startup folder if Task Scheduler refuses. The same `service start`,\n`service stop`, and `service restart` commands work in either mode. It is not a\nWindows Service; it runs as you, because Codex runs as you.\n\nBecause yes, Windows gets nice things too.\n\n## Requirements\n\n- Windows\n- Codex installed and signed in\n- A Telegram bot token from `@BotFather`\n- Telegram threaded topics enabled for the bot\n\nIn `@BotFather`, enable:\n\n```text\nBot Settings -\u003e Threads Settings -\u003e Threaded Mode\n```\n\n## Setup\n\n### Option 1: Install The Latest Release\n\nRun the installer from PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/yashau/dexgram/main/install.ps1 | iex\n```\n\nIt downloads the latest release, installs `dexgram.exe` under\n`%LOCALAPPDATA%\\Dexgram`, adds that folder to your user `PATH`, creates the\nconfig/log/state directories, and starts onboarding.\n\nAfter onboarding, validate the setup:\n\n```powershell\ndexgram -check\n```\n\nStart Dexgram in the foreground:\n\n```powershell\ndexgram\n```\n\nOr install the background login task so it starts when you sign in:\n\n```powershell\ndexgram service install\ndexgram service start\n```\n\nUpdate later from PowerShell:\n\n```powershell\ndexgram update\n```\n\nYou can also update from Telegram with `/update`. Dexgram announces before it\nrestarts and again after it comes back, which is exactly the kind of civilized\nbehavior a bridge should have.\n\n### Option 2: Manual Setup\n\nIf you already have `dexgram.exe`, run onboarding:\n\n```powershell\n.\\dexgram.exe onboard\n```\n\nOnboarding asks for your BotFather token and Codex defaults. If no Telegram\nchats are authorized yet, start Dexgram, then DM the bot or add it to a group\nand send a message. The bot replies with the exact command to add that chat.\n\nYou can also keep a local config beside the binary:\n\n```powershell\nCopy-Item .\\dexgram.example.toml .\\dexgram.toml\n.\\dexgram.exe onboard\n```\n\nMinimum config:\n\n```toml\n[telegram]\nbot_token = \"123456789:replace-me\"\nchat_ids = []\n```\n\n## Pair A Telegram Chat\n\nUnauthorized chats cannot use Codex, and Telegram slash commands are not\nregistered for them. They only get setup instructions.\n\nSend any message from an unauthorized chat. Dexgram replies with a short-lived\npairing code and a ready-to-run command:\n\n```powershell\ndexgram telegram chatid add ABC-234\n```\n\nThe code is case-insensitive and may be entered as `ABC-234` or `ABC234`. Direct\nnumeric chat IDs still work too, including negative group IDs:\n\n```powershell\ndexgram telegram chatid add -1001234567890\n```\n\nAliases:\n\n```powershell\ndexgram tg id add ABC-234\ndexgram telegram chatid del \u003cchat_id\u003e\ndexgram telegram chatid clear\n```\n\nDexgram hot-reloads the config, so adding or removing chats does not require a\nrestart.\n\nTo rotate the bot token without putting it in shell history:\n\n```powershell\ndexgram telegram token update\n```\n\nThe running bridge reconnects with the new token after the config reloads.\n\n## Service Mode\n\nDexgram can install itself as a user-login background process:\n\n```powershell\ndexgram service install\ndexgram service start\ndexgram service restart\ndexgram service status\n```\n\nThis is not a Windows Service. It runs as the signed-in user so it can talk to\nthe same Codex environment.\n\nService paths:\n\n```text\nBinary: %LOCALAPPDATA%\\Dexgram\\dexgram.exe\nConfig: %APPDATA%\\Dexgram\\dexgram.toml\nLogs:   %APPDATA%\\Dexgram\\dexgram.log\nState:  %APPDATA%\\Dexgram\\dexgram.db\n```\n\nThe service log keeps the newest 5000 lines.\n\n## Telegram Commands\n\nCommands are registered only for authorized chats.\n\n- `/sessions [query]` opens the session browser. Dexgram lists projects first,\n  then paginated Codex threads inside the selected project. Attach one to the\n  current Telegram topic and Dexgram syncs the most recent 25 rendered history\n  messages by default. New completed Desktop replies after attach are mirrored\n  into the topic with the Desktop prompt quoted before the reply.\n- `/new [title]` creates a new topic for a one-off Codex chat.\n- `/new project query: title` creates a new topic already bound to a matched\n  Codex project.\n- `/side [message]` or `/btw [message]` forks the current Codex chat into a\n  prefixed side topic.\n  If `message` is present, Dexgram starts it in the new side topic immediately.\n  The source topic must already be an active registered Codex thread.\n- `/project \u003cproject name\u003e` binds a new topic to a Codex project before\n  the first prompt. Ambiguous matches get inline selection buttons.\n- `/status` shows the topic mapping, project/cwd, and active turn state.\n- `/usage` shows Codex 5-hour and weekly usage limits.\n- `/sync [limit]` mirrors completed Codex turns that have not been synced yet.\n  It defaults to 1 turn, caps at 5 turns, and truncates oversized historical\n  output.\n- `/update` updates Dexgram and restarts the bridge.\n- `/steer \u003cmessage\u003e` steers the currently active Codex turn.\n- `/goal` shows the current native Codex goal for the topic. `/goal \u003cobjective\u003e`\n  sets it. `/goal pause` stores the current goal by Codex thread id, then clears\n  it in Codex. `/goal resume` restores that stored goal. `/goal clear` clears\n  without storing it; `delete`, `remove`, `stop`, `off`, and `none` are aliases.\n- `/plan \u003cmessage\u003e` starts a Codex Plan Mode turn.\n- `/settings` shows Telegram-started Plan Mode settings.\n- `/model [model-id|auto]` chooses the Plan Mode model.\n- `/effort [auto|minimal|low|medium|high|xhigh]` chooses reasoning effort.\n- `/stop` or `/cancel` interrupts the active Codex turn.\n\n## How Chats Run\n\nOn the first prompt in a Telegram topic that has no project or Codex thread,\nDexgram asks whether to resume an existing session, start a new chat, or set a\nproject first.\n\n- **Resume a session** opens the `/sessions` browser, attaches the selected\n  Codex thread to the topic, syncs recent history, starts live Desktop reply\n  mirroring, then submits your waiting message.\n- **Start new chat** creates a fresh Codex thread for that topic.\n- **Set project first** lets you bind the topic with `/project` before sending\n  work to Codex.\n\nOnce a choice creates or attaches a Codex thread, Dexgram saves the mapping by\nTelegram `chat_id` and `message_thread_id`. Later messages in that topic reuse\nthe stored Codex thread.\n\n### Existing Sessions\n\n`/sessions [query]` is the fast lane back into work you already started. Dexgram\nasks Codex for recent threads, groups them by project/cwd, and shows an inline\nproject tree. Pick a project, pick a thread, and the current Telegram topic is\nattached to that Codex session.\n\nAttach sync is intentionally bounded. Dexgram mirrors up to the most recent 25\nrendered Telegram history messages so you get context without flooding the\ntopic. After attach, Dexgram records the last Telegram activity time for the\ntopic, watches Codex's session JSONL file only for recently active mapped\ntopics, and mirrors new completed Desktop turns after the saved sync marker.\nOld inactive mappings remain available for `/sessions`, `/status`, and manual\n`/sync`, but they do not keep live mirror workers running. Mirrored Desktop\nreplies include the Desktop prompt as a Markdown quote before the answer.\nManual `/sync [limit]` is also bounded: one completed turn by default, five at\nmost.\n\nDexgram also mirrors Telegram prompts back into the Codex Desktop transcript.\nWhen a Telegram message is sent into an existing Codex thread after at least one\ncompleted turn, Dexgram writes a passive `Telegram: ...` transcript entry into\nCodex's session JSONL just before starting the Codex turn. These entries are\ntagged with a top-level `dexgram` metadata object for debugging and duplicate\ntracking, and Dexgram filters `Telegram:` transcript entries out of\nDesktop-to-Telegram mirroring to avoid feedback loops. Codex Desktop does not\nhot-reload these inserted transcript entries; restart or reload Codex Desktop to\nsee Telegram-origin messages appear in the desktop chat.\n\n### Side Chats\n\nUse `/side` or `/btw` inside an existing Codex topic to open a separate side\ntopic from the current context. Dexgram names side topics with a `↳N` prefix,\nsuch as `↳1 Dexgram: auth flow`, while leaving the parent topic name unchanged.\n\nSide chats are real Codex thread forks. They keep the parent topic's project and\ncwd, can call tools, ask for approvals, run commands, edit files, and continue\nindependently after the fork. You can create multiple side chats from the same\nparent topic; each one gets the next number.\n\n`/side` and `/btw` are guarded: they only work after the source topic has\nalready started and registered a Codex thread. A fresh `/new` topic or\nproject-only topic needs its first normal Codex message before it can be forked.\nDexgram starts a fresh app-server for the side topic, creates the ephemeral\nfork there, and keeps that app-server attached to the new topic.\n\nYou can also include the first side-chat prompt in the command:\n\n```text\n/side check whether the auth refactor missed tests\n```\n\nDexgram creates the side topic and starts that prompt there immediately.\n\nWithout `/project`, Dexgram creates a projectless workspace under:\n\n```text\n%USERPROFILE%\\Documents\\Codex\\YYYY-MM-DD\\chat-title\n```\n\nEach Codex turn appears in Telegram as:\n\n- An initial assistant or plan message, when Codex sends one.\n- One live run-log message for commands, tools, edits, searches, and media.\n- The final assistant answer.\n\nLive status and run-log messages are sent silently. Final answers, approval\nprompts, and user-input prompts use normal Telegram notifications.\n\n## Queued Messages\n\nIf you send a message while Codex is already working in that topic, Dexgram\nqueues it locally and submits it when earlier work finishes.\n\nQueued user messages get two inline buttons:\n\n- `Steer` merges the queued input into the active Codex turn.\n- `Delete` removes it before it is submitted.\n\n`/steer \u003cmessage\u003e` does the same thing from text.\n\n## Files And Attachments\n\nDexgram downloads Telegram photos, image documents, and regular documents to\nlocal files before sending them to Codex. Images are passed as local image\ninputs; other documents are included by absolute path.\n\nText plus files is sent as one prompt. Files without text are staged and\nattached to the next message in that chat.\n\nBy default, final answers stay text-only. To upload local files explicitly\nlinked by the final answer:\n\n```toml\n[telegram]\nupload_final_answer_files = true\n```\n\nImages are sent as photos. Everything else is sent as a document.\n\n## Limitations\n\n- Dexgram can attach existing Codex sessions exposed by Codex app-server, but it\n  does not bulk-import your entire Codex history into Telegram.\n- Attach sync is capped at the most recent 25 rendered Telegram messages. New\n  completed Desktop replies after attach are mirrored into the attached topic,\n  with the Desktop prompt quoted above the reply.\n- Telegram prompts are appended into Codex's session JSONL as `Telegram: ...`\n  transcript entries, but Codex Desktop shows them only after the desktop thread\n  is reloaded or Codex is restarted.\n- Manual `/sync` is intentionally capped and truncated so one command cannot\n  flood a topic with a huge historical transcript.\n- Dexgram is Windows-only by design.\n\n## Development\n\nRun the same checks used by GitHub Actions:\n\n```powershell\n.\\scripts\\check.ps1\n```\n\nThe script verifies `gofmt`, runs tests and coverage, and runs the pinned\n`golangci-lint`.\n\nVersion metadata lives in `cmd/dexgram/versioninfo.json`. Regenerate the Go and\nWindows resource files with:\n\n```powershell\ngo generate ./cmd/dexgram\n```\n\nOn pushes to `main`, CI runs the shared check. If no GitHub release exists for\n`v\u003cversion\u003e`, CI builds `dexgram.exe`, writes a SHA-256 checksum, and publishes\nboth files.\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyashau%2Fdexgram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyashau%2Fdexgram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyashau%2Fdexgram/lists"}