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 --telegramsession. 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
Create a bot with @BotFather and copy the token.
Find your numeric Telegram user id. Send your bot any message, then run:
bashcurl -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.
Write
~/.pi/agent/telegram.json(keep any existing content), referencing the token by environment variable:json{"profiles": {"default": {"botToken": "$TELEGRAM_BOT_TOKEN", "allowedUserId": 123456789}}}Start the TUI with the token exported in the same shell:
bashexport TELEGRAM_BOT_TOKEN='123456:ABC...' autorag tui --telegramIn the TUI, run
/telegram-connect. You should see the bridge connect.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:
| Command | Purpose |
|---|---|
/telegram-setup | Save the bot token (optionally for a named profile). |
/telegram-connect | Start polling and bind this session (optionally a named profile). |
/telegram-status | Show connection state and recent events. |
/telegram-disconnect | Stop 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, andwrite. Treat the bot token andallowedUserIdas credentials for a shell on your machine. - The bot token and pairing live in
~/.pi/agent/telegram.json(underPI_CODING_AGENT_DIRif set), never in AutoRAG config. - The prompt queue is per session. Anything waiting when the process exits is lost and not replayed.
- A bridged
tuidefaults tofullpermission 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:
tmux new -s autorag
autorag tui --telegram # then /telegram-connect
# detach: Ctrl+b d reattach: tmux attach -t autoragThe session stops if the machine sleeps or reboots.
Troubleshooting
| Symptom | Cause |
|---|---|
Footer shows disconnected | The session is configured but not polling. Run /telegram-connect. |
not configured | The token is missing, or $TELEGRAM_BOT_TOKEN is not set in the shell that started the TUI. |
Telegram connection failed | Run /telegram-status --debug and read the recent runtime events. |
Verify the token with:
curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getMe" | jq '{ok, username: .result.username}'