# Grok Telegram Bot πŸ€– > **Control [Grok CLI](https://grok.dev/cli/) from Telegram.** Your AI coding > assistant in your pocket β€” switch projects, resume and attach to live coding > sessions, stream answers with diffs, queue follow-ups, and run it 24/7 as a > background service on Windows, Linux, and macOS. ![Node](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white) ![Platforms](https://img.shields.io/badge/platforms-Windows%20%7C%20Linux%20%7C%20macOS-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![Powered by](https://img.shields.io/badge/powered%20by-Grok%20CLI-orange) A professional Telegram bridge that drives the official **Grok Build CLI** (`grok`) over the **Agent Client Protocol (ACP)** β€” `grok agent stdio` β€” and turns it into a mobile, always-on AI pair programmer. Sign in with your xAI account (SuperGrok / X Premium+), send a message from anywhere, and watch Grok plan, read files, run commands, and edit code on your machine β€” with live typing indicators, clean Telegram markdown, and unified edit diffs. A fork of [`artickc/kiro-telegram-bot`](https://github.com/artickc/kiro-telegram-bot), re-architected for the Grok Build CLI and extended into a full multi-session client. --- ## ✨ Features | Capability | What it does | |---|---| | πŸ—‚ **Projects** | `/projects` browses your folders and runs Grok in the one you pick. | | 🏷 **Forum project topics** | Optional forum supergroup: **General** manager, **AI Chat** workspace, one topic per project, exact-name bind, `/forum_setup`. See **[docs/GROUP.md](./docs/GROUP.md)**. | | πŸŽ› **General manager** | Forum General is a chat-like orchestrator: memory-first, short replies, `send_prompt` into project topics, report-back when child work finishes. | | πŸŒ‰ **Telegram bridge** | Agent can `create_topic`, `set_path`, `send_prompt` (optional `session_id`), `notify`, `search_memory`, `list_topics` / `list_jobs`, and call allowlisted sibling bots via JSON actions. | | πŸ”– **Prompt anchors** | Each user prompt is re-posted with a searchable `#prompt_…` tag; stream/Done messages reply to that anchor (media re-attached). | | πŸ†• **New session** | `/new` or the bar **New** button starts a fresh session; forum topics keep New on the topic menu. | | πŸ’‘ **Post-turn suggestions** | After Done, 1–3 scored follow-ups as buttons; high-score items can auto-queue as one multi-step prompt. | | πŸ” **Gated self-recheck** | After file-changing turns, an optional quality pass runs once before Done (`SELF_RECHECK`). | | ♻️ **Resume sessions** | `/sessions` lists recent Grok sessions; tap to resume one (`grok --session `). | | 🟒 **Connect to live sessions** | `/active` shows sessions running **right now** on your PC. Watch them live, or continue them β€” see below. | | πŸ›‘ **Kill a session / PID** | Each live `/sessions` Β· `/active` card has a **πŸ›‘ Kill Β· pid N** button (confirm-guarded) that stops that session's process and its child tree; `/killall` stops them all. The bot's own agent is never killable. **Stop** only cancels the current session turn β€” never the shared agent. | | πŸ“‘ **Live watch** | Follow a running session read-only in real time (tails its event log). | | 🧭 **Always-visible menu** | A persistent keyboard plus a pinned status panel that appears while a task runs (and clears when idle), showing your current **project, agent, reasoning effort, model, session and queue**. | | ⏰ **Scheduled tasks** | Create prompts that run on a schedule (once / daily / weekly / monthly / every-N-minutes) in a chosen project, delivered back to your chat. | | πŸ–Ό **Multi-image prompts** | Send one or many photos (albums included) with a caption β€” all attached to the prompt for the agent to analyze. | | πŸ“œ **History** | `/history` shows the latest messages of any session. | | 🧩 **MCP control** | `/mcp` lists MCP servers, **health-checks** them (which connected / failed and why), and **enables/disables** them β€” then restarts the agent to apply. | | πŸ‘₯ **Subagent visibility** | When Grok delegates to subagents and waits on them, you see each one **start / work / finish** plus a live `πŸ€– N running` summary β€” and subagent permission prompts route to your chat. | | πŸ“ˆ **Task progress bar** | The agent appends a `{progress: N%}` marker; the bot hides it and shows a **green 0–100% loading bar** on the live message, in the status panel, and on session cards (`SHOW_PROGRESS`). | | πŸ” **Sign in from chat** | `/reauth` signs you in without a terminal β€” **πŸ”‘ Sign in** runs headless `grok login --device-auth` (link/code streams to your chat, no host browser), or **πŸ“₯ Import** an existing on-host login; the agent restarts under the new identity. | | πŸ‘₯ **Multiple accounts** | `/accounts` saves several Grok **sign-ins** (custom names) and switches between them in a tap β€” **stops the agent β†’ replaces `~/.grok/auth.json` β†’ restarts headlessly** (never opens a browser). | | πŸ” **Auto-rotate on give-up** | When a turn exhausts its retries (or hits **402 balance exhausted** with no same-account retry), optionally cycle through your other saved accounts once: stop CLI β†’ swap `auth.json` β†’ restart + re-auth β†’ retry. First that works wins (toggle in `/accounts`). | | βœ… **Auto-approve tools** | By default, ACP permission prompts are auto-approved for the **session** (`AUTO_APPROVE_PERMISSIONS`). Turn both that and `GROK_TRUST_ALL_TOOLS` off for interactive Approve/Deny β€” those prompts are **pinned** until you act. | | πŸͺ™ **Credits & usage** | The `βœ… Done` line and `/usage` show credits used (when Grok reports them), turns this session, and account info. | | ⌨️ **Typing indicator** | Stays on for the whole turn, even through long tool chains. | | πŸ“₯ **Queued follow-ups** | Message while Grok is busy β€” it's queued and runs next. `/btw` runs it ASAP (now if idle, else right after the current task); `/flush` runs the queue now. | | ✏️ **Edit diffs** | File edits show as unified `diff` blocks with `+N -M` stats. | | πŸ’¬ **Quality markdown** | Converts agent markdown to Telegram **MarkdownV2** with safe escaping and code-fence-aware splitting. | | πŸ” **Self-healing** | Auto-restarts the Grok agent with backoff and re-binds your session. | | πŸ–₯ **Runs 24/7** | 1-click install as a background service that starts on boot β€” Windows, Linux, macOS, auto-detected. | | πŸ”’ **Access control** | Restrict to specific Telegram user IDs (private chats **and** forum groups). | --- ## πŸ“Š How it compares | Capability | **This bot** | Other Grok Telegram bots | |---|:---:|:---:| | Connect Grok CLI to Telegram (ACP) | βœ… | βœ… | | Switch between projects | βœ… | ❌ | | **Forum topics = projects** + AI Chat workspace | βœ… | ❌ | | **General manager** (memory-first, dispatch + report-back) | βœ… | ❌ | | **Cross-topic agent bridge** (create / bind / send_prompt / session_id) | βœ… | ❌ | | Resume saved sessions | βœ… | ❌ | | Attach to **live** PC sessions (watch / fork) | βœ… | ❌ | | **Kill a session by PID** (or all at once) | βœ… | ❌ | | **Live task-progress bars** (`{progress: N%}`) | βœ… | ❌ | | **Sign in from chat** (`/reauth`, device-code) | βœ… | ❌ | | **Multiple saved accounts** + headless one-tap switch (`/accounts`) | βœ… | ❌ | | **Auto-rotate accounts** when a turn gives up | βœ… | ❌ | | **Session auto-approve** + **pinned** interactive permissions | βœ… | ❌ | | Multiple isolated sessions | βœ… | ❌ (single shared) | | Queued follow-ups while busy | βœ… | ❌ | | **Post-turn suggestions** + gated self-recheck | βœ… | ❌ | | **Scheduled tasks** (cron-like) | βœ… | ❌ | | **Multi-image** prompts (albums) | βœ… | ❌ | | Unified **edit diffs** | βœ… | ❌ | | Persistent menu + live status panel | βœ… | ❌ | | Agent / reasoning / model menus | βœ… | ❌ | | Combined, throttled output (no spam) | βœ… | ❌ | | Auto-restart + session re-bind | βœ… | ❌ | | 24/7 cross-platform service | βœ… | ❌ | | 1-click install | βœ… | ❌ | --- ## ⚑ Install from npm The fastest way β€” one command installs the global **`grok-tg`** CLI (ships with the `tsx` runtime, no build step): ```bash npm install -g grok-telegram-bot ``` By default your config lives in a **canonical, path-independent home** β€” `~/.grok/tg/` (its `.env`, `logs/`, `data/`) β€” so the bot loads the **same** `.env` no matter which folder you start it from. Run `grok-tg setup --path` to print the exact location. (A `.env` in the current folder is still honoured first, so existing per-folder checkouts keep working.) ```bash grok-tg setup # auto-detects grok, writes ~/.grok/tg/.env grok-tg setup --path # print the .env location # edit that .env: set TELEGRAM_BOT_TOKEN and ALLOWED_USERS grok-tg run # foreground … grok-tg install # … or install as a 24/7 background service ``` The bot is **single-instance per token**: starting it again terminates any ghost/duplicate that was still polling Telegram (the usual cause of a stale "β›” Not authorized"), so the fresh process with your current `.env` wins. A plain `grok-tg run` yields to an already-running background service instead. Want a **second Telegram bot** (one private chat per project) without switching sessions? Create another bot in @BotFather and: ```bash grok-tg --name work setup grok-tg --name work install grok-tg instances ``` Each named instance has its own `~/.grok/tg/instances//` and unique service (`grok-telegram-bot-work`). The default bot is unchanged. Startup options: `grok-tg [--name ] setup [--path] | run | install | status | logs [n] | stop | restart | uninstall | instances`. Or try it without installing: `npx grok-telegram-bot setup`. See **[docs/INSTALL.md](./docs/INSTALL.md)** for the full guide. **Already installed?** See **[docs/UPGRADE.md](./docs/UPGRADE.md)** to update to the newest version β€” global npm installs auto-update when idle, or run `npm install -g grok-telegram-bot@latest` and `grok-tg restart`. --- ## πŸš€ 1-click install Clone or download, then run the installer for your OS. It installs dependencies, auto-detects `grok`, writes `.env`, asks for your bot token, and optionally sets up the background service. **Windows** β€” double-click `install.cmd` (or in a terminal): ```powershell .\install.cmd ``` **Linux / macOS**: ```bash chmod +x install.sh && ./install.sh ``` ### Prerequisites - **Grok Build CLI** (`grok`) installed β€” `curl -fsSL https://x.ai/cli/install.sh | bash` (Windows: `irm https://x.ai/cli/install.ps1 | iex`). Run `grok --version` to confirm. - A **SuperGrok** or **X Premium+** subscription, and a one-time sign-in: run `grok login` (browser OIDC) on the host, or use the bot's `/reauth`. On a headless host with no browser you can instead set `XAI_API_KEY`. - **Node.js 20+**. - A **bot token** from [@BotFather](https://t.me/BotFather). - Your **Telegram user ID** from [@userinfobot](https://t.me/userinfobot). > ⚠️ **Use a dedicated bot token.** Telegram allows only one long-polling > consumer per token. If you also run another Telegram bot (e.g. a Kiro bridge) > on the **same** token, they will clash on `getUpdates`. This bot keeps its > own config home (`~/.grok/tg`) and only ever manages its **own** sessions > (`/sessions`), so it never touches Kiro's processes or session locks β€” > but give it its own BotFather token to avoid the polling conflict. --- ## πŸ§‘β€πŸ’» Manual setup ```bash npm install npm run setup # auto-detects grok + project roots, writes .env # edit .env: set TELEGRAM_BOT_TOKEN and ALLOWED_USERS npm start ``` No build step β€” TypeScript runs directly via `tsx`. --- ## πŸ›  Run as a background service (daemon) The bot installs as a **user-level** service that starts automatically on boot. The platform is auto-detected: | OS | Mechanism | Starts on | |---|---|---| | Windows | Hidden Scheduled Task (elevated) Β· per-user **Startup folder** (no admin) | logon | | Linux | systemd **user** service (+ linger) | boot | | macOS | launchd LaunchAgent | login | On Windows, registering a logon-triggered Scheduled Task needs admin, so from a normal terminal `grok-tg install` falls back to a hidden launcher in your per-user **Startup folder** (starts at logon, no elevation). Run it from an **elevated** terminal to use the Scheduled Task instead; either way `status`, `stop`, `restart` and `uninstall` work the same. ```bash npm run install:service # install + start, enable autostart npm run service -- status # show install + running state npm run service -- stop npm run service -- restart npm run service -- logs 200 # tail the log file npm run uninstall:service # stop + remove ``` Or use the `grok-tg` command (if linked): `grok-tg install | status | logs`. Logs are written to `logs/grok-telegram-bot.log` (rotated at 5 MB). --- ## πŸ’¬ Commands ``` /menu Show the persistent menu keyboard /projects List Β· /projects search Β· /projects open any folder Β· /projects new /sessions List & resume sessions (active first) Β· /sessions to filter /active Sessions running now on the PC /running Sessions this chat controls β€” switch between them /killall Kill all active sessions on the PC (with confirm) /mcp Inspect MCP servers Β· health-check Β· enable/disable /tasks Manage scheduled tasks /newtask Create a scheduled task (wizard) /history Show recent conversation history /new Start a fresh session here (also bar: πŸ†• New session) /forum_setup Re-probe / create forum topics (use inside the configured group) /status Current session, project & queue /usage Account info & current context usage /btw Run it now if idle, else queue to run right after the current task /flush Send queued follow-ups now /queue Show queued follow-ups /clearqueue Clear the queue /cancel Stop the current turn (session-scoped β€” never kills the shared agent) /stop Same as /cancel /unwatch Stop following a live session /model Switch the model for this session /restart Restart the Grok agent /reauth Sign in to Grok β€” πŸ”‘ Sign in (grok login) or πŸ“₯ Import an existing login /accounts Save & switch between multiple Grok accounts Β· auto-rotate on errors /help Show help ``` Anything that isn't a command is sent to Grok as a prompt. While a turn is running, your messages are queued and sent automatically when it finishes. --- ## 🏷 Forum project group (optional) Drive **many projects in parallel** from one Telegram forum supergroup: each topic is bound to a folder, and **AI Chat** stays on `GROK_WORKSPACE` for orchestration. Set `TOPIC_GROUP_ID`, make the bot admin with Manage Topics, and run `/forum_setup`. Full walkthrough (binding rules, agent bridge, access control, troubleshooting): **β†’ [docs/GROUP.md](./docs/GROUP.md)** --- ## 🧭 The menu & status panel A tiny **persistent bar** sits under the message box β€” **☰ Menu Β· πŸ†• New session Β· 🧭 Running Β· ⏹ Stop** (while idle/busy the middle button may show Running instead of New) β€” so common actions are one tap away without clutter. Tap **☰ Menu** (or `/menu`) to open a clean, grouped **inline menu**: Project Β· Running Β· Sessions Β· Agent Β· Model Β· Reasoning Β· Tasks Β· Status Β· Usage Β· Stop Β· Kill all. Forum topics keep **New** on the topic inline menu (reply keyboards are unreliable there). The bar can be hidden (πŸ™ˆ) and restored (⌨️ Show bar or `/menu`). While a task is running, a **pinned status panel** appears at the top of the chat showing your current **task progress, activity, queue, project, session, context %, agent, reasoning effort and model** (and how many sessions the chat controls), updating live β€” and it's **removed when the session goes idle** so the chat stays clean between tasks (use **Status** in the menu to see it on demand any time). Pick **Agent**, **Reasoning** or **Model** from the inline menu (reasoning steers how thoroughly the agent works: Minimal β†’ Max). ## ⏰ Scheduled tasks A task is a **prompt + a project + a schedule**. When it fires, the bot opens a session in that project, runs the prompt, and delivers the result to your chat. - **/newtask** (or the βž• button) launches a guided wizard: name β†’ prompt β†’ project β†’ schedule β†’ confirm. - **Schedules**: `once` at a date/time, `daily` at HH:MM, `weekly` (e.g. `Mon 09:00`), `monthly` (e.g. `15 09:00`), or `interval` (every N minutes). - **/tasks** lists everything with buttons to **run now, enable/disable, edit** (rename, prompt, project, reschedule) and **delete**. Tasks are stored in `data/tasks.json` and survive restarts; the scheduler runs them whether you're online or not (great with the 24/7 service). ## πŸ–Ό Sending images Send one or several photos β€” including a Telegram **album** β€” with an optional caption. The bot downloads them and attaches them all to the prompt as image content blocks, so the agent can analyze them together. Images sent while Grok is busy are queued with your next turn. **Images come back too:** when the agent produces images during a turn β€” Imagine `image_gen` / `image_edit` (written under `~/.grok/sessions///images/` and `…/assets/`), screenshots, or files under `/images/` β€” the bot detects the freshly-written files and sends them back to Telegram as **downloadable documents** (`SEND_AGENT_IMAGES`, default on). Prompts also include image-output rules so the agent keeps gens in the session media folder and reports absolute paths. ## πŸŽ™ Sending voice Send a voice note, audio file, or video note and the bot runs it as a prompt **only when STT is configured**. Set any OpenAI/Whisper-compatible endpoint via `STT_API_URL` (and `STT_API_KEY` if needed). The bot transcribes, shows the quote, and submits plain text. Without `STT_API_URL`, voice is rejected with a short β€œnot configured” message β€” Grok Build CLI rejects ACP `audio` content blocks, so raw audio cannot be heard by the agent. Leave `STT_LANGUAGE` blank for automatic detection (English, Russian, Romanian/Moldovan, and ~100 more). ## πŸ“Ž Sending files Send any **document** and the bot resolves it. **Text-like files** β€” a long message your Telegram client turned into a `.txt`, plus code, logs, JSON, CSV, Markdown, and more β€” are downloaded, decoded, and inlined into the prompt (up to `DOC_MAX_CHARS`, then truncated with a note), so the agent reads the whole thing. **Binary files** are saved under `/downloads` and their path is handed to the agent to open with its own tools. An optional caption becomes the instruction; files sent while Grok is busy are queued with your next turn. ## ↩️ Replying for context **Reply** to any message (yours or the bot's) and the referenced content rides along with your new message, so a terse "fix this" or "why?" keeps its meaning. If you highlight a specific **quote** while replying, the bot forwards that exact excerpt plus the surrounding message. Works for text, photo, voice and file prompts alike (long quotes are trimmed to keep prompts lean). ## πŸ“ˆ Task progress The bot asks the agent to end each message with a `{progress: N%}` marker, then **hides the marker** and renders a **green loading bar** from 0–100 % (`🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜ 50%`, all-green βœ… at 100 %) so you can see how far along the current task is. The bar appears at the bottom of the **live message**, in the pinned **status panel**, and on **`/running` and `/sessions` cards**. Markers are also stripped from history, replays and previews, so the raw plumbing never shows. Turn it off with `SHOW_PROGRESS=false`. That marker is only an instruction the model can ignore β€” weaker/free models and long, tool-heavy turns often emit none, which used to leave the bar empty for the whole turn. So when `SHOW_PROGRESS` is on but no marker arrives, the bot falls back to a **computed** bar derived from real activity (completed tool calls, streamed output, elapsed time): it starts low, climbs as work advances, and fills to 100 % when the turn completes. The agent's own marker, when present, always takes precedence and the value never decreases. Disable the fallback with `PROGRESS_FALLBACK=false`. ## πŸ” Signing in to Grok Grok Build signs in with your **xAI account** (SuperGrok / X Premium+), not an API key. Run **`/reauth`** to sign in without touching a terminal: - **πŸ”‘ Sign in** β€” runs `grok login --device-auth` (device code, **no browser on the host**). The verification link/code streams into the chat so you can approve it on any device. The bot then restarts the agent under the new identity. - **πŸ“₯ Import existing** β€” adopt a `grok login` already done on this machine (`~/.grok/auth.json`). It's refused while a turn is running. You can also sign in up front by running `grok login` on the host, or set `XAI_API_KEY` on a headless host. ## πŸ‘₯ Multiple accounts **`/accounts`** manages several Grok **sign-ins** side by side. Save the current login as a named account (auto-named from its email when available, or **Save as…** with a custom name), rename or delete saved ones, and **switch** in a tap. Switching is deliberately headless: 1. Snapshot the current login (so it isn't lost), 2. **Stop** the shared agent, 3. **Replace** `~/.grok/auth.json` with the saved snapshot, 4. **Start** the agent and authenticate with `cached_token` only β€” never a browser method like `grok.com` (which would hang a service host). The menu shows the **host Grok login** vs which saved account it matches, so a manual `grok login` outside the bot doesn't leave a stale β€œactive” label. **πŸ” Auto-rotate on errors** (toggle here): when a turn exhausts its retries and can't recover, the bot cycles through your other saved logins **once** with the same stop β†’ auth.json β†’ start path β€” the first that succeeds stays active; if they all fail it stops after one pass. Handy when an account gets throttled or runs out of quota. --- ## 🧭 Working on several sessions at once One chat can drive **multiple Grok sessions** and switch between them. Start a session (πŸ“ Project / πŸ†• New), and each becomes a "controlled" session. Tap **🧭 Running** (or `/running`) to switch: the foreground session streams live while the others keep working quietly. When you switch to a session you see its recent context and **every message that arrived while you were away** (its unread, recovered from the session log). Leave a task running in A, hop to B, reply, and come back to A to read what it did. Close a session with βœ– (it isn't killed) β€” or tap **πŸ›‘ Kill Β· pid N** on its `/sessions` Β· `/active` card to stop its process (and `/killall` to stop them all). ## πŸ”— Connecting to live sessions While a turn is running, the bot marks that session busy (a `.lock` with the live `grok` child's pid), so a second turn can't collide with it. You can still: - **πŸ“‘ Watch** β€” follow the running session's output live (read-only) by tailing its event log. Stop with `/unwatch`. - **Continue (fork)** β€” tapping a live session opens a **linked continuation** in the same project, primed with the recent transcript, so you can keep interacting from Telegram without disturbing the running turn. Resuming an **idle** session loads it directly so you continue the exact thread. --- ## βš™οΈ Configuration (`.env`) | Variable | Required | Default | Description | |---|---|---|---| | `TELEGRAM_BOT_TOKEN` | **yes** | β€” | Bot token from @BotFather. | | `ALLOWED_USERS` | recommended | *(all)* | Comma-separated Telegram user IDs for private chats **and** groups. Empty = anyone (unsafe β€” never leave empty with `TOPIC_GROUP_ID`). Unauthorized group members are ignored silently. | | `GROK_CLI_PATH` | no | auto / `grok` | Path to the `grok` binary. | | `GROK_WORKSPACE` | no | cwd | Default working directory (also AI Chat / General in a forum group). | | `XAI_API_KEY` | no | β€” | xAI API key, only for headless hosts with no browser. Normally you sign in with `grok login` (or `/reauth`) β€” no key needed. Exported to the agent when set. | | `GROK_MODEL` | no | `grok-4.5` | Default model for new sessions. | | `GROK_TG_DIR` | no | `~/.grok/tg` | Folder holding this instance's `.env`, `logs/`, `data/`. Resolution: `--instance` β†’ `GROK_TG_DIR` β†’ a `.env` in the current folder β†’ `~/.grok/tg`. So a `.env` created once is loaded from any startup path. | | `GROK_AGENT` | no | β€” | Custom sub-agent name (informational; Grok delegates via its own `task`/`delegate` tools). | | `GROK_TRUST_ALL_TOOLS` | no | `true` | Pass `--always-approve` so tools run without prompts. | | `AUTO_APPROVE_PERMISSIONS` | no | `true` | Auto-approve ACP `session/request_permission` (prefer β€œallow for this session”). Set `false` **and** `GROK_TRUST_ALL_TOOLS=false` for interactive Approve/Deny buttons (those prompts are **pinned** until you act or they time out). | | `PROJECT_ROOTS` | no | workspace parent + home | Roots for `/projects`. | | `STREAM_THROTTLE_MS` | no | `1500` | Live-edit interval while streaming. | | `MESSAGE_BATCH_MS` | no | `800` | Window to coalesce rapid text messages (e.g. a long message Telegram split at 4096 chars) into one prompt. `0` disables. | | `SHOW_TOOL_CALLS` | no | `true` | Show tool-call status messages. | | `SHOW_EDIT_DIFFS` | no | `true` | Show unified diffs for edits. | | `DIFF_MAX_LINES` | no | `120` | Max diff lines shown inline. | | `DOC_MAX_CHARS` | no | `100000` | Max characters of a **text file** attachment inlined into the prompt (a long message Telegram turned into a `.txt`, plus code, logs, JSON, CSV, …). Longer files are truncated with a note; binaries are saved under `/downloads` and their path is handed to the agent. `0` = unlimited. | | `SHOW_SUBAGENTS` | no | `true` | Stream subagent (crew) start/work/finish while the main agent waits. | | `SHOW_PROGRESS` | no | `true` | Ask the agent to append a `{progress: N%}` marker to each message; the bot parses it, hides the marker, and renders a green 0–100% bar on the live message, in session cards, and in the status panel. | | `PROGRESS_FALLBACK` | no | `true` | When `SHOW_PROGRESS` is on but the agent emits **no** `{progress: N%}` marker (weaker/free models and long tool-heavy turns often skip it), render a **bot-computed** bar derived from real activity (completed tool calls, streamed output, elapsed time) so a live bar still advances β€” filling to 100% when the turn completes. The agent's own marker, when present, always takes precedence and stays monotonic. | | `NOTIFY_OTHER_SESSIONS` | no | `true` | Deliver a session's "Done" summary (with a short created/edited/deleted count) even when it's a background session, marked "From other session". `false` keeps background sessions silent. | | `SUGGESTIONS_ENABLED` | no | `true` | After Done, quietly ask for 1–3 scored follow-ups shown as buttons. | | `SUGGESTIONS_AUTO_APPROVE_PCT` | no | `95` | Auto-queue suggestions with need β‰₯ this % as one multi-step prompt (`0` = buttons only). | | `SELF_RECHECK` | no | `true` | After a successful user turn that modified files, optionally run one gated quality pass before Done. Alias: `SLEF_RECHECK`. | | `SELF_RECHECK_PROMPT` | no | β€” | Optional fixed recheck template when AI decides recheck is needed (`{{USER}}` / `{{DONE}}`). | | `QUIET_PROMPT_TIMEOUT_MS` | no | `90000` | Max wait for quiet meta prompts (recheck decision + suggestions). Timeout cancels the meta prompt so Done is not blocked. | | `TOPIC_GROUP_ID` | no | β€” | Forum supergroup id for project topics. Bot must be admin with Manage Topics. See **[docs/GROUP.md](./docs/GROUP.md)**. | | `TOPIC_AUTO_CREATE` | no | `true` | When forum is ready, create one topic per catalog project (paced + 429-retried). | | `TOPIC_AI_CHAT_NAME` | no | `AI Chat` | Display name for the workspace topic. | | `ALLOWED_TELEGRAM_BOTS` | no | β€” | Comma-separated sibling bot usernames the agent may call via bridge `bot_command` / `list_bots`. | | `TELEGRAM_BOT_COMMANDS` | no | β€” | Optional command catalogs for sibling bots (compact or JSON; see `.env.example`). | | `TELEGRAM_BOT_REPLY_TIMEOUT_MS` | no | `45000` | Hard timeout waiting for a sibling bot after `/cmd@bot`. | | `TELEGRAM_BOT_SETTLE_MS` | no | `2000` | Quiet settle after the last message/edit from that bot. | | `MCP_PROBE_TIMEOUT_MS` | no | `8000` | Per-server timeout for the `/mcp` live health-check. | | `MCP_PROBE_CONCURRENCY` | no | `6` | How many MCP health probes run at once. | | `GROK_AUTO_RESTART` | no | `true` | Auto-restart the agent if it exits. | | `GROK_TG_SINGLE_INSTANCE` | no | `true` | Enforce one running bot **per token**: on startup a still-alive ghost/duplicate (an old process polling Telegram with a stale `.env`, the usual cause of a phantom "β›” Not authorized") is terminated so the fresh process wins. A manual `run` yields to an already-running background service instead of fighting it. | | `AUTO_UPDATE` | no | `true` | Hourly check npm and, when a newer version exists **and the bot is idle** (no turn/task running, no other active Grok session), auto-update + restart + post the release notes (tagged `#update`). Global npm installs only. | | `UPDATE_CHECK_MS` | no | `3600000` | How often to check npm for updates (ms). | | `PROMPT_RETRY_ATTEMPTS` | no | `5` | Max retries for a transient agent error (e.g. high-traffic / `Internal error`) before any output streamed, with `6s β†’ 12s β†’ 24s β†’ 48s β†’ 60s` backoff. The real error shows each attempt; a summary after the last. `0` disables. | | `AUTO_FORK_ON_ERROR` | no | `true` | When the retries above are exhausted on a transient error (throttle / `Internal error` / exhausted context) and nothing streamed, **logically fork** the session β€” open a fresh continuation primed with the recent transcript, drop the stuck session, and retry the message once. | | `AUTO_FORK_CONTEXT_PCT` | no | `85` | When a prompt fails transiently **and** the session's last-known context usage is at/above this %, **skip the retry backoff and fork immediately** β€” a context-exhausted session won't recover by retrying the same oversized prompt (throttling on a near-full session shows up as `-32603 … throttled`). Forking compacts it into a fresh continuation primed with the recent transcript. Requires `AUTO_FORK_ON_ERROR`; `0` disables this trigger. | | `RESUME_ON_STREAM_ERROR` | no | `true` | When a transient error (throttle / `Internal error` / dropped response stream) strikes **after the reply already began streaming**, the retry/fork/rotate paths above are skipped (re-sending would re-run tools that already executed). Instead the bot asks the **same session to continue** from where it stopped β€” the partial reply and completed tool results are already in history, so nothing is repeated β€” using the same backoff so the throttle can clear. Skipped for context-full sessions (they can't recover by continuing). | | `LOG_LEVEL` | no | `info` | `debug` \| `info` \| `warn` \| `error`. | | `LOG_DIR` / `LOG_FILE` | no | `/logs/…` | Log location. | --- ## 🧩 How it works ``` Telegram ──HTTPS──▢ Bot (grammY) β”‚ spawns once β–Ό grok agent stdio ◀── JSON-RPC 2.0 over stdio (ACP) ──▢ Bot β”‚ β”œβ”€ initialize / authenticate (cached login / API key) β”œβ”€ session/new Β· session/load (projects, resume) β”œβ”€ session/prompt (your messages) └─ session/update (streamed text, tools) ``` One `grok agent stdio` process multiplexes many sessions. After `initialize` the bot runs `authenticate` (using the cached `grok login` token, or `XAI_API_KEY`), then streamed `agent_message_chunk` updates are assembled into a live, throttled message and `tool_call` updates render as status lines with diffs. The bot records the sessions **it** drives on disk under `/sessions/`: `.json` (metadata), `.jsonl` (history, used by `/history` and live watch), and `.lock` (written while a turn runs, for active detection). This layout is entirely separate from any Kiro bridge, so the two never collide. --- ## πŸ“ Project layout ``` src/ β”œβ”€β”€ index.ts Entry point, daemon-friendly logging, shutdown β”œβ”€β”€ cli.ts CLI: run / install / start / stop / status / logs β”œβ”€β”€ config.ts .env loading, paths, daemon options β”œβ”€β”€ logger.ts Leveled logger with file output β”œβ”€β”€ grok/ Grok bridge: headless client, JSONL types, models, session log β”œβ”€β”€ sessions/ Session discovery, history parser, live tail watcher β”œβ”€β”€ projects/ Project directory discovery β”œβ”€β”€ forum/ Forum topic store, path bind, project icons β”œβ”€β”€ mcp/ MCP config (list/toggle) + live health probe β”œβ”€β”€ render/ Markdownβ†’MarkdownV2, diffs, tool formatting, chunking β”œβ”€β”€ stream/ Incremental edit-streaming β”œβ”€β”€ service/ Cross-platform daemon (windows/linux/macos + selector) └── bot/ grammY bot, per-chat runtime, handlers, Telegram bridge ``` --- ## ❓ FAQ **Can I run the Grok Telegram bot 24/7 on a server?** Yes β€” `npm run install:service` installs a user-level service (systemd/launchd/Scheduled Task) that starts on boot and auto-restarts on crash. **How do I control Grok from my phone?** Set up the bot, message it on Telegram, and pick a project with `/projects`. Every message becomes a Grok prompt. **Can multiple people use one bot?** Add their IDs to `ALLOWED_USERS`. Each chat gets its own session. **Why can't I take over a session that's already running?** Grok locks active sessions exclusively. The bot lets you **watch** it live or **fork** a linked continuation instead. See "Connecting to live sessions". **Does it support custom agents and MCP servers?** Yes β€” set `GROK_AGENT`, and the bot inherits whatever MCP servers Grok CLI is configured with. --- ## πŸ” Tool approvals Over ACP, Grok honors a permission mode. Defaults are built for unattended mobile use: | Setting | Default | Effect | |---|---|---| | `GROK_TRUST_ALL_TOOLS` | `true` | Passes `--always-approve` so tools run without prompts. | | `AUTO_APPROVE_PERMISSIONS` | `true` | If a permission request still arrives, auto-pick **allow for this session** / always-allow. | Set **both** to `false` for ACP **"ask"** mode: Grok sends `session/request_permission` before risky tools and the bot surfaces **Approve / Allow for session / Deny** buttons. Those prompts are **pinned** so they aren't buried by streaming output; the pin is removed when you choose, or when the request times out (status panel is re-pinned). You can always intervene on a live turn with the tool stream + **⏹ Stop** (`/cancel`). ## πŸ” Security This bot lets authorized Telegram users run commands and edit files on the host. **Always set `ALLOWED_USERS`**, keep `.env` private, and run as a non-privileged user. See [SECURITY.md](./SECURITY.md) for the full model. --- ## πŸ—Ί Roadmap - [x] Projects, resume & attach to live sessions - [x] Queued follow-ups, edit diffs, quality MarkdownV2 - [x] Persistent menu + live status panel (project / agent / reasoning / model) - [x] Scheduled tasks (once / daily / weekly / monthly / interval) - [x] Multi-image prompts (albums) - [x] Combined, throttled output (anti-spam) - [x] 24/7 cross-platform background service - [x] Voice messages β†’ STT (`STT_API_URL`) β†’ text prompt (disabled without STT) - [x] Agent-generated images β†’ Telegram document files (session `images/`/`assets/`) - [x] Context-usage % in the status panel - [x] Inline approvals β€” approve/deny risky tools from buttons (non trust-all mode) - [x] Session auto-approve + pinned permission prompts - [x] Account & context usage (`/usage`) - [x] Multiple accounts with headless one-tap switch + auto-rotate (`/accounts`) - [x] Device-code `/reauth` (no host browser) + real email labels from auth.json - [x] Rich per-kind tool-call detail (search / edit diffs / shell / MCP / …) - [x] README community sections β€” Contributors, Top Contributors, Stars, StarMapper - [x] Forum project topics + AI Chat workspace (`TOPIC_GROUP_ID`) - [x] Cross-topic Telegram bridge (`create_topic` / `set_path` / `send_prompt` / …) - [x] Prompt anchors, post-turn suggestions, gated self-recheck - [ ] **Token & cost meter** β€” per-session token counts and an estimated spend tally - [ ] **Text-to-speech replies** β€” optionally speak answers back as voice notes - [ ] **Scheduled-task chaining & conditions** β€” run task B after A, or only if a command/file check passes - [ ] **Team mode** β€” roles and audit log beyond shared `ALLOWED_USERS` + forum topics - [ ] Localized bot UI (i18n) - [ ] Docker image with `grok` preinstalled - [ ] Webhook mode for serverless deployment Have an idea? Open a [feature request](../../issues/new/choose). ## 🀝 Contributing Contributions are very welcome! See **[CONTRIBUTING.md](./CONTRIBUTING.md)** to get started β€” no build step is required (`npm run dev`), and `npm run typecheck` must pass. New here? Look for issues labeled [**good first issue**](../../issues?q=is%3Aopen+label%3A%22good+first+issue%22) and [**help wanted**](../../issues?q=is%3Aopen+label%3A%22help+wanted%22). By participating you agree to the [Code of Conduct](./CODE_OF_CONDUCT.md). --- ## πŸ‘₯ Contributors [![Contributors](https://contrib.rocks/image?repo=artickc/grok-telegram-bot&max=100&columns=20&anon=1)](https://github.com/artickc/grok-telegram-bot/graphs/contributors) ### How to Contribute 1. Fork the repository 2. Create your feature branch (`git checkout -b feat/amazing-feature`) 3. Commit your changes (`git commit -m 'Add amazing feature'`) 4. Push to the branch (`git push origin feat/amazing-feature`) 5. Open a Pull Request See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines. ### Releasing a New Version ```bash # Bump the version, update CHANGELOG.md, then push a tag. # The release workflow builds a downloadable zip and publishes notes automatically. npm version minor # or: patch / major β€” updates package.json + commits git push --follow-tags # pushing the v* tag triggers .github/workflows/release.yml ``` --- ## ⭐ Top Contributors > This project is built and maintained in the open. These people have made the > contributions that shape its quality, stability, and reach. **Thank you.**
artickc
artickc
πŸ₯‡ Maintainer
Created the bot: Grok headless bridge, multi-session
runtime, scheduler, daemon & renderer
> πŸ™ Every pull request, bug report, and idea matters. Open source is built by > people like them β€” see the full list under [Contributors](#-contributors). --- ## πŸ“Š Stars Star History Chart If this project helps you, please consider giving it a ⭐ β€” it really helps! --- ## 🌍 StarMapper > See where in the world this project's stargazers live β€” an interactive map of > the community. StarMapper β€” where this project's stargazers live --- ## πŸ“¦ Download & Releases Grab the latest packaged build from the [**Releases**](https://github.com/artickc/grok-telegram-bot/releases) page β€” each release ships a clean `grok-telegram-bot-.zip` (no `node_modules` or secrets) plus GitHub's source archives. See [CHANGELOG.md](./CHANGELOG.md) for what changed in each version, **[docs/INSTALL.md](./docs/INSTALL.md)** for the full 1-click install guide, **[docs/UPGRADE.md](./docs/UPGRADE.md)** for how to update an existing install (npm, zip, or source), and **[docs/GROUP.md](./docs/GROUP.md)** for forum project topics. --- ## πŸ“„ License [MIT](./LICENSE) β€” see also [CONTRIBUTING](./CONTRIBUTING.md) and [Code of Conduct](./CODE_OF_CONDUCT.md). --- Keywords: Grok CLI Telegram bot, xAI Grok coding agent, AI coding assistant on Telegram, mobile AI pair programming, remote coding agent, run AI agent as a service, Windows/Linux/macOS daemon, ChatOps for developers.