Skip to content

Telegram ​

autorag tui --telegram lets you ask the librarian questions from a Telegram chat while a TUI session is running on your machine. It loads @llblab/pi-telegram (pinned 0.58.3).

A question you send the bot runs through the same Jev routing and two-phase search as the same text typed in the terminal, and the answer comes back in the chat. A message sent while a search is running steers that search, exactly like pressing Enter in the TUI. The bridge's [telegram] and [time] envelope is stripped, so the librarian sees only your words.

Requirements ​

  • A running autorag tui --telegram session. The bridge is an extension of that process: if the TUI exits, Telegram stops answering.
  • A Telegram bot token from @BotFather (/newbot).
  • Outbound HTTPS only. No inbound port is opened.

Setup ​

  1. Create a bot with @BotFather and copy the token.

  2. Find your numeric Telegram user id. Send your bot any message, then run:

    bash
    curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates" | jq '.result[].message.from | {id, username}'

    Do this before connecting; a connected bridge consumes the same updates.

  3. Write ~/.pi/agent/telegram.json (keep any existing content), referencing the token by environment variable:

    json
    {"profiles": {"default": {"botToken": "$TELEGRAM_BOT_TOKEN", "allowedUserId": 123456789}}}
  4. Start the TUI with the token exported in the same shell:

    bash
    export TELEGRAM_BOT_TOKEN='123456:ABC...'
    autorag tui --telegram
  5. In the TUI, run /telegram-connect. You should see the bridge connect.

  6. Message the bot from your own account.

Alternatively, run /telegram-setup in the TUI and paste the token. Without allowedUserId, the first account to send /start becomes the only allowed owner, so set allowedUserId up front.

Commands ​

In the TUI:

CommandPurpose
/telegram-setupSave the bot token (optionally for a named profile).
/telegram-connectStart polling and bind this session (optionally a named profile).
/telegram-statusShow connection state and recent events.
/telegram-disconnectStop polling and release ownership.

In the bot chat: /start (menu and pairing), /new, /compact, /next, /continue, /abort, /stop, and /name. The hidden compatibility shortcuts /help, /status, /model, /thinking, /queue, and /settings jump into the same menu system.

Behavior ​

  • Telegram sessions have the same tools as the TUI, including bash, edit, and write. Treat the bot token and allowedUserId as credentials for a shell on your machine.
  • The bot token and pairing live in ~/.pi/agent/telegram.json (under PI_CODING_AGENT_DIR if set), never in AutoRAG config.
  • The prompt queue is per session. Anything waiting when the process exits is lost and not replayed.
  • A bridged tui defaults to full permission because there is no terminal dialog; an explicit --permission-mode, AUTORAG_PERMISSION_MODE, or config value still wins.
  • autorag search (print/JSON modes) never polls Telegram.

Keeping it running ​

The bridge does not start a background process of its own. To keep the session alive after closing the terminal, run the TUI under tmux:

bash
tmux new -s autorag
autorag tui --telegram      # then /telegram-connect
# detach: Ctrl+b d    reattach: tmux attach -t autorag

The session stops if the machine sleeps or reboots.

Troubleshooting ​

SymptomCause
Footer shows disconnectedThe session is configured but not polling. Run /telegram-connect.
not configuredThe token is missing, or $TELEGRAM_BOT_TOKEN is not set in the shell that started the TUI.
Telegram connection failedRun /telegram-status --debug and read the recent runtime events.

Verify the token with:

bash
curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getMe" | jq '{ok, username: .result.username}'

Released under the Apache-2.0 license.