Grok Telegram Bridge 0.5.1

Grok Telegram Bridge 0.5.1

A small bugfix release: a dead turn no longer freezes the whole lane.

What is new since 0.5.0

• A cancelled turn releases the worker right away. If a turn that had
  already used tools was cancelled (Esc in the terminal) or crashed, no final
  answer row ever lands in the session log, and the bridge used to keep
  waiting for it until the full GRB_TUI_ANSWER_TIMEOUT window (2 hours by
  default) ran out - with every queued message stuck behind it. The wait loop
  now double-checks the TUI screen for its busy hints (the spinner status
  line and the cancel hint in the footer); when the no-progress window has
  passed and two consecutive probes both see an idle screen, the turn is
  treated as dead and the worker moves on with a clear reason in the error
  message. When the probe is unsure (capture fails, blank pane) it keeps
  waiting - a live turn is never cut on a broken instrument.
• Kill switch. Set GRB_TUI_DEAD_TURN_PROBE=0 to restore the previous
  behavior; GRB_TUI_DEAD_TURN_PROBE_GAP (seconds, default 3) controls the
  gap between the two idle probes.
• Backlog log lines now carry a timestamp, so a stuck queue can be
  correlated with process restarts after the fact.

v0.5.0

Grok Telegram Bridge 0.5.0

A small release that finishes the local-mirror story: what happens at the
machine now shows up on the phone with nothing missing.

What is new since 0.4.0

• A terminal /clear shows up on the phone too. Rebuilding the TUI
  session from the terminal side used to be invisible in Telegram, so the
  chat looked like it silently forgot everything. The bridge now sends the
  same short session-clear notice it already sent for a phone-side /clear.
• Locally injected input is mirrored as the question. When a prompt
  enters the tmux session from the machine side (a local relay, a voice
  front-end, your own paste), the chat now shows that input as the question
  the moment it is queued - the answer no longer arrives without the
  question that caused it. Part of the GRB_TUI_MIRROR_LOCAL axis, off by
  default.

Progress-line editing, copy-paste command bubbles, late-answer recovery,
/clear / /new session rebuild, and inbound media remain from 0.4.0.

Security

Unchanged. One chat-id check is still the entire defense. Read the README
before installing. Do not share the bot token. Do not add the bot to a group.

Requirements

Python 3, tmux for the terminal lane, and the Grok CLI installed and signed
in. Linux, macOS, or WSL on Windows.

There is still no PyPI package and no setup wizard. Install is git clone
and two environment variables.

v0.4.0 — progress edit, command bubbles, late-answer recovery

Grok Telegram Bridge 0.4.0

Brings the public package in line with the maintainer's live bridge after
three days of daily use.

What is new since 0.3.0

• One progress line, edited in place. In the TUI lane, a long turn no
  longer stacks a new Telegram bubble every minute. One status message is
  rewritten as work continues.
• Copy-paste command bubbles. A command the answer wants you to run is
  sent as its own message with Telegram's copy button, not left inside the
  prose.
• Late answers are recovered. A turn that overruns the wait, a bridge
  restart mid-turn, a conversation that rotated underneath, or a compressed
  history file no longer throws away a finished answer that arrived a moment
  later.
• Text no longer brings a leftover photo. A clipboard image was riding
  along with a text paste and showing up as an attachment Grok never asked
  for. That path is stripped.
• /clear and /new rebuild the TUI session. The bridge restarts the
  pane instead of pasting those words into Grok. Confirmation on the phone
  is a short text line, not a large decoration.
• Optional local mirror. Set GRB_TUI_MIRROR_LOCAL=1 if you type into
  the tmux session on the machine and also want those turns on your phone.
  Off by default.

Photos, video, voice, files inbound, suggested-reply split, and the confirm
button remain from 0.2.0 / 0.3.0.

Security

Unchanged. One chat-id check is still the entire defense. Read the README
before installing. Do not share the bot token. Do not add the bot to a group.

Requirements

Python 3, tmux for the terminal lane, and the Grok CLI installed and signed
in. Linux, macOS, or WSL on Windows.

There is still no PyPI package and no setup wizard. Install is git clone
and two environment variables.

v0.3.0 — suggested-reply split and confirm button

Grok Telegram Bridge 0.3.0

Brings the public package in line with the maintainer's live bridge.

What is new since 0.2.0

• Suggested-reply split. A trailing suggestion marker at the end of an
  answer is sent as a second Telegram message, not left in the body.
• Confirm button. That second message has a confirm button. Pressing it
  sends the suggestion back into the same Grok session.
• Photos, video, voice, files inbound, and long-tool idle handling remain
  from 0.2.0.

The public splitter only looks at a marker at the very end of the answer. It
does not include the maintainer's extra repair rules for broken tags.

Security

Unchanged. One chat-id check is still the entire defense. Read the README
before installing. Do not share the bot token. Do not add the bot to a group.

v0.2.0 — media inbound and current-main export

Grok Telegram Bridge 0.2.0

Upgrade of the public bridge to the internal build that shipped after v0.1.0.

What is new

• Photos, video, voice, and files inbound. A Telegram message that is only a photo (no caption) is no longer dropped. The bridge downloads the file and hands it to Grok as a local path plus caption.
• Long tool-using turns stay alive. While a tool call is open, quiet JSONL is treated as work in progress, not as idle. A three-minute silence no longer cuts a turn that is still running a command.
• Confirm-button plumbing is in the tree. The maintainer's private build also splits a trailing suggested-reply marker into a second bubble with a confirm button. The public build still sends the answer as one message (the sister parser is not part of this package), so you will not see that button here. The download and callback helpers remain so a later public split can reuse them.

Packaging

The export script no longer dies when deliver_mesh_event gains a keyword argument. v0.1.0 could not be regenerated from current main until that anchor was loosened.

Security

Unchanged from v0.1.0. One chat-id check is still the entire defense. Read the README before installing. Do not share the bot token. Do not add the bot to a group.

Requirements

Python 3, tmux for the terminal lane, and the Grok CLI installed and signed in.

v0.1.0 — first public release

First public release.

Text your own private Telegram bot, and the message runs as a Grok turn on your computer. Grok's finished answer comes back to your phone.

This is a sibling of the Claude Telegram Bridge and the Codex Telegram Bridge. It targets Grok specifically and shares no runtime code with either.

Read the security section before installing

This bridge gives a chat app the ability to run commands on your computer. Grok is allowed to use its real tools: run shell commands, read files, edit files, run git.

The only thing between the internet and your machine is one check — the bridge compares the Telegram chat id of every incoming message against the single chat id you configured, and discards everything else. There is no command allowlist, no approval prompt, no sandbox, and no second factor.

Never share your bot token, never add the bot to a group, and do not run this on a machine you cannot afford to have damaged. The README covers this in full; please read it first.

What is in this release

• Telegram long-polling loop with single-chat-id enforcement
• Two lanes: a headless lane and a terminal (tmux) lane that mirrors a live Grok session
• Typing and progress indicators while a turn is running
• Idle-based waiting: a turn that keeps making progress keeps going, while a silent turn is cut, so long tool-using work is no longer truncated at a fixed deadline
• Account profile separation, so more than one Grok account can be used from separate home directories
• Session launcher with retry on startup, so a restart that fails once does not leave you with no window
• Example configuration file and a public test suite

Requirements

Python 3, tmux for the terminal lane, and the Grok CLI installed and signed in.

Install

Clone the repository, copy the example configuration, fill in your bot token and chat id, then run the bridge. Step-by-step instructions are in the README.