v2.5.0

What's new in 2.5.0

Forum project topics, cross-topic Telegram bridge, prompt anchors, and a more
reliable Done / stop path for multi-topic groups.

Added

• Forum project topics (optional). TOPIC_GROUP_ID manages a Telegram forum
  supergroup: default AI Chat topic (workspace), optional auto-create one
  topic per catalog project (TOPIC_AUTO_CREATE), favicon/MSIX logo discovery
  pinned in the topic, and path-binding when users create new topics. Messages
  in a topic run sessions in that project path.
• Telegram bridge actions (agent JSON). On the first prompt of a session the
  bot injects how-to-work memory: the agent may emit a fenced json block with
  "telegram": [ actions ] to create forum topics, search session/topic memory,
  list allowlisted sibling bots, and call them via /cmd@bot (MCP-like). Results
  are fed back as a quiet follow-up turn (not a Done). Configure bots with
  ALLOWED_TELEGRAM_BOTS, optional TELEGRAM_BOT_COMMANDS catalogs, reply
  timeout / settle (TELEGRAM_BOT_REPLY_TIMEOUT_MS, TELEGRAM_BOT_SETTLE_MS).
  Sibling-bot waits only accept content from the triggered bot (prefer reply-to
  our trigger), collect edits until idle, and timeouts continue the session.
  Bridge plumbing stays out of the chat (no “continuing session” / queue spam);
  only durable side-effects like topic creation are announced.
• Cross-topic bridge actions. From General / AI Chat (GROK_WORKSPACE), the
  agent can orchestrate other forum topics via telegram JSON:
  • create_topic with optional path
  • set_path — bind/rebind a topic to an absolute path or exact catalog name
  • send_prompt — inject a prompt into another topic’s session (ran/queued;
    does not wait for that turn). Optional new_session.
    Multiple actions run in order (cap 9; up to 5 send_prompt per turn).
    New project paths: agent create_topic / set_path with an absolute path
    that does not exist yet creates the folder on disk, then binds the topic.
• New session on the persistent bar + /new. Private chat: bar is
  ☰ Menu · 🆕 New session / 🧭 Running · ⏹ Stop (not the inline Menu message).
  Slash command /new (Telegram command list) starts a fresh session. Forum
  topics keep New on the topic inline menu because reply keyboards are unreliable.
• Instant command feedback. Slash commands and bar taps are deleted
  immediately; handlers post bot status messages (e.g. /new →
  “Creating new session…”) so the chat feels alive while the CLI/ACP starts.
• Prompt anchors + #prompt_<id>. User prompts (text, photos, docs, voice,
  /btw, suggestion taps) are re-posted as bot messages with a searchable
  #prompt_ tag; the originals are best-effort deleted. Photos, documents, and
  voice/audio are re-attached on the anchor via Telegram file_id so media is
  not lost when the user message is removed. All AI stream bubbles, Done/error
  notices, and queue acks for that turn reply to the anchor and carry the same
  tag (alongside #proj_ / #sess_).

Changed

• Session card comments. Cards (/running, /sessions, /active, status
  panel) now show the last user prompt (max 250 chars). While a session is
  running, a second line shows the last AI agent thinking (max 250). Idle
  cards no longer use last-turn assistant outcome summaries as the comment.
• Stronger self-recheck prompts. Decision + default recheck briefs now push
  production-related completeness for the same feature (e.g. water→waves,
  auth→rate limits), finish-all (no “still need…” / incomplete honest
  leftovers that force critical follow-up buttons), and a required per-bug
  recheck checklist at the end of the pass. Compose always injects those
  rules when an AI brief looks complete (headers only) but omitted them.
  /new, bar New, and inline New share the same success copy.

Fixed

• Missing ✅ Done after a turn. Done no longer waits on suggestion JSON
  (send Done first, then attach buttons). Quiet meta prompts (recheck decision
  • suggestions) use QUIET_PROMPT_TIMEOUT_MS (default 90s) and cancel the
    session prompt on timeout so a hung meta call cannot block Done forever
    (does not set user-cancelled / does not kill the agent). Chat shows
    “Checking if a quality pass is needed…” while deciding recheck. Done text is
    rebuilt after that wait so /stop mid-decision shows ⏹ Stopped. notify
    retries truncated/plain text if the first send fails; a finally safety net
    forces a short Done when one was expected but never delivered.
• /stop / /cancel must not kill the bot or other sessions. Stop is
  session-scoped only: soft ACP session/cancel, cancel pending permissions
  for that session, and force-complete that session’s in-flight prompt after a
  short grace if the agent is slow — never kill the shared grok agent
  process (which multiplexes every chat/topic). killPid also refuses to
  target the bot’s own Node process.
• grok-tg install|start|restart hang on Windows. The service VBS is a
  forever-restart loop (Run …, True waits for the bot). Launching it with
  execFileSync made the CLI wait forever. Startup launches now use detached
  spawn so the CLI returns immediately.
• No silent process death. Exit paths always log reason + code to stderr/file;
  instance-lock conflict uses exit 1; polling classifies 429/409/401/network with
  backoff; interactive runs recover in-process (no detach re-exec that blanks the
  terminal); ref'd keepalive every 5m; beforeExit keeps the process up if the
  event loop empties unexpectedly. Updater re-exec inherits TTY stdio.
• Markdown / tool path rendering. File paths in tool cards (Edit/Read/…) are
  no longer wrapped in bold (Windows C:\… paths broke MarkdownV2 and fell
  back to plain text that clients soft-render as **Edit C:**). Paths use
  inline code; plain fallback demotes **/fences so soft-render cannot mangle
  them. Chunked fences preserve tick length when reopening.
• Group / topic stop controls. Forum topic menu leads with Stop + Running;
  /cancel and /stop work in topics; group slash-command menu is a short,
  sorted list with cancel first (private keeps the full sorted catalog). Stop
  confirms in-thread (not only a toast).
• Forum topic bind: exact name only. New user topics auto-bind when the
  topic title exactly matches a catalog project (case-insensitive). Path prompts
  and first messages no longer use fuzzy/partial project search (which could
  bind the wrong folder). Unmatched topics still accept an absolute path or an
  exact catalog name.
• Forum bulk topic create. Startup//forum_setup walks the full project
  catalog (not a 200-item cap), paces creates, and retries on Telegram 429
  (retry_after) and transient network errors so large catalogs (1000+) can
  finish reliably across restarts.
• Forum group readiness. Setup probes the configured group: if the bot is
  not admin (or lacks Manage Topics), the group is ignored for topic
  features. If Topics are off, the bot best-effort tries to enable them (no
  official Bot API method today), otherwise ignores the group with a clear
  status. Re-probes on promotion via my_chat_member; /forum_setup reports
  ready vs disabled reason.

Docs

• README updated for forum topics, bridge, prompt anchors, suggestions,
  self-recheck, and related config.
• docs/GROUP.md — how to set up and use a forum project
  group (binding, bridge actions, access control, troubleshooting).

---

Install: npm install -g grok-telegram-bot@2.5.0 then grok-tg restart

Forum groups: see docs/GROUP.md

Full install guide: docs/INSTALL.md

v2.4.0

[2.4.0] - 2026-08-01

Added

• Post-turn suggestions. After Done, quietly ask for 1–3 follow-ups with a need score (0–100). Shown as inline buttons; items at/above SUGGESTIONS_AUTO_APPROVE_PCT (default 95) run as one numbered multi-step prompt.
• Gated self-recheck. After a successful user turn with file changes, a quiet AI decision may refuse recheck or write a focused recheck prompt that runs once before Done. Env: SELF_RECHECK / SLEF_RECHECK, optional SELF_RECHECK_PROMPT.
• Auto complexity steering. First prompt steers Simple vs Complex; plan-mode exit auto-approved.
• Plan board rendering. Live plan entries with progress.
• Session import. Import external session transcripts.
• Richer tool / file / markdown rendering. Tool-call detail, file op summaries (first-turn vs recheck split), session card comments, Markdown fence safety.
• Usage / accounts menu polish.

Fixed / hardened

• Near-100% bot lifetime. Poll restart, uncaught stay-up, ACP/createBot retries, lock heartbeat, Windows VBS forever-restart, stop kills VBS host.
• Self-recheck / queue safety. mergeInputs preserves skipSelfRecheck; meta turns flush alone; cancel during decision does not queue recheck.
• Plan exit reliability. Correct ACP method and approval payload.

npm: npm i -g grok-telegram-bot@2.4.0

v2.3.1

Fixed

• Serialized process-global account rotation so concurrent chats reuse the working account selected by the first rotation.
• Rebind stale ACP sessions on unknown session id, agent restart/process exit, and headless-auth initialization errors without rotating functional accounts.
• Propagate credential-driven restarts to every chat runtime and delay new session binding until account candidate validation completes.

Verification

• npm run typecheck
• npm test — 40 passed

v2.3.0

What's new in v2.3.0

Added

• Instant project switch — no more wait on ACP session/new; session binds lazily on first message
• Image-output prompt rules — keep gens in session media folder and report absolute paths

Fixed

• Agent images as Telegram files (sendDocument) — scans session images/ + assets/
• Stale callback queries — safe/idempotent answers; answer before slow ACP work
• Voice requires STT again — needs STT_API_URL (CLI cannot hear raw audio)
• Non-blocking session handoff — switch stays responsive while prior turns run

v2.2.4

Fixed

• 🚫 Rotate immediately on Grok access denial. API 403 Forbidden / Access denied responses now bypass same-account retry backoff, mark the failed
  login with ⚠️, and rotate to the next eligible saved account. If the active
  host login was not already saved (for example after an external sign-in or
  token refresh), it is captured first so the warning is visible and persists.
• 🔐 Isolated Grok Telegram identity. The Grok bot now takes its Telegram
  token from its own instance .env before considering an inherited process
  environment value. This prevents a machine-wide token for a sibling bot from
  making Grok poll as Codex/Kiro/OpenCode and causing Telegram conflicts.
• ⚠️ Persistent account warnings. Account access/quota failures are shown
  in /accounts, excluded from later automatic rotations, and can be manually
  re-enabled after the account is repaired.
• 🛟 No false success for silent ACP turns. A Grok ACP completion with no
  text, thought, or tool update is now treated as a recoverable agent failure
  instead of reporting Done · no text output.

v2.2.3 — instant account rotate on 402 balance exhausted

Fixed

• Instant account rotate on 402 balance exhausted. Grok Build Payment Required / usage balance exhausted errors (usually wrapped as ACP Internal error [-32603]) are no longer treated as transient. Same-account backoff retries are skipped. With auto-rotate ON, the bot immediately: stops the Grok CLI → swaps ~/.grok/auth.json → restarts the CLI with headless cached_token auth → opens a fresh session → retries the same prompt. If that account fails, it switches to the next saved account (one pass). If all accounts fail (or auto-rotate is OFF), the turn stops with a clear error. Telegram shows Account switched to … because of: … plus a CLI-restart notice.

npm i -g grok-telegram-bot@2.2.3

v2.2.2 — multi-account, auto-approve, pinned permissions

Grok Telegram Bot v2.2.2

The 2.2.x multi-account + permissions batch, documented and hardened.

Highlights since v2.1.0

Multi-account (headless)

• Account switch & auto-rotate never open a browser. Flow: stop agent → replace ~/.grok/auth.json → start with headless cached_token only. Browser methods like grok.com are never selected.
• Auto-rotate on give-up (toggle in /accounts): one pass over saved accounts; first success wins.
• Real emails from auth.json entry fields (modern tokens often omit email claims).
• Active account = live token hash — no stale “active” after an outside grok login.
• /reauth uses grok login --device-auth (device code in Telegram, no host browser).
• Agent spawn uses --no-leader so auth.json swaps take effect.

Permissions

• AUTO_APPROVE_PERMISSIONS=true (default) — auto-approve ACP prompts, preferring “allow for this session”.
• Interactive mode (trust-all + auto-approve both off): Approve/Deny prompts are pinned until approve, deny, or timeout; status panel re-pinned after.

Tool visibility (2.1.0)

• Rich per-kind tool-call detail: search, read, edit diffs, write, delete, move, execute, fetch, web search, MCP — with ✅/❌ completion status.

Install / upgrade

npm install -g grok-telegram-bot@2.2.2
# or
npm install -g grok-telegram-bot@latest
grok-tg restart   # if installed as a service

Links

• npm: https://www.npmjs.com/package/grok-telegram-bot
• Changelog: https://github.com/artickc/grok-telegram-bot/blob/main/CHANGELOG.md
• Docs: https://github.com/artickc/grok-telegram-bot#readme

v2.2.1

Permission prompts are pinned while waiting for Approve/Deny, then unpinned on approve, deny, or timeout (status panel re-pinned afterwards).

v2.1.0 - First Stable Release

First Stable Release - v2.1.0

Grok Telegram Bot is now stable. This is the first production-ready release with all features complete and verified.

Control the official Grok Build CLI (grok) from Telegram over the Agent Client Protocol (ACP). Sign in with your xAI account, switch projects, resume sessions, stream responses with live diffs, queue follow-ups, manage multiple sign-ins, and run 24/7 as a cross-platform background service.

---

Complete Feature Set

• Projects and Sessions - Browse folders, create projects, resume/attach to live sessions, multi-session control with /running
• Streaming and Rendering - Live typing indicators, MarkdownV2 rendering, unified edit diffs, chunking for long messages
• Tool Call Visibility - Rich detail for every tool: searches (pattern + scope + filters), reads (path + line/offset), edits (diff blocks with stats), writes (content preview + syntax highlighting), deletes, moves (source to dest), shell commands (bash blocks), fetches (URL + method + body), web searches, MCP calls (server + method + args)
• Tool Status Tracking - See pending to completed/failed for each tool call as it completes
• Subagent Visibility - Watch subagents start, work, and finish in real-time
• Auth and Accounts - xAI account sign-in (grok login), XAI_API_KEY support, multi-account with /accounts, auto-rotate on failure
• Self-Healing - Auto-fork on context-full, transient-error retry with backoff, auto-restart, single-instance guard
• Progress Bar - Live {progress: N%} bar with bot-computed fallback
• Scheduled Tasks - Run tasks on a schedule with /tasks
• Voice Messages - Transcribe voice to prompts (configurable STT endpoint)
• Image Prompts - Send photos to the agent, receive generated images back
• File Ingestion - Send documents for the agent to read
• MCP Control - /mcp to inspect, health-check, enable/disable MCP servers
• Inline Approvals - Approve/deny risky tool calls from Telegram buttons
• Cross-Platform Daemon - Windows (Startup folder / Task Scheduler), Linux (systemd), macOS (launchd)
• npm Package - npm install -g grok-telegram-bot gives you the grok-tg CLI
• Auto-Update - Checks hourly, updates when idle
• Status Panel - Pinned live status with activity, location, config, progress
• Threaded Replies - Every message threaded to your prompt with searchable hashtags
• Self-Cleaning UI - Transient menus auto-remove for a tidy chat history

---

Install

npm install -g grok-telegram-bot
grok-tg setup    # configure .env + detect grok CLI
grok-tg install  # install as 24/7 background service

Or see the Install Guide.

---

Architecture

A fork of artickc/kiro-telegram-bot, re-architected for the Grok Build CLI (grok agent stdio) over ACP.

• Runtime: Node.js >= 20, TypeScript via tsx (no build step)
• Key deps: grammy (Telegram), dotenv, diff
• Entry point: src/index.ts / CLI/daemon: src/cli.ts

---

Full changelog: CHANGELOG.md