Telegram
Mercury connects to Telegram via a bot token, providing a mobile-first interface with streaming, file uploads, inline approval keyboards, and real-time task progress.
Access Model
Mercury uses an organization access model with admins and members. The first user becomes the admin by completing a pairing-code flow during setup. Additional users request access by sending /start, which admins can approve or reject.
When no admins exist yet, sending /start creates a pairing code that must be entered in the CLI to complete setup. This ensures only the legitimate owner can gain initial access. Once an admin exists, new users send /start to create a pending request that admins can approve or reject.
Mercury only works in private (one-to-one) chats. Messages in groups or channels are always ignored.
Roles
| Role | Description | Can approve requests? |
|---|---|---|
| Admin | First user to pair. Can approve/reject access requests, promote/demote users, and reset all access. | Yes |
| Member | Approved by an admin. Can send messages and receive responses. | No |
| Pending | Sent /start but not yet approved. Can only see their pending status. | No |
CLI Commands
| Command | Description |
|---|---|
mercury telegram list | Show approved admins, members, and pending requests |
mercury telegram approve <code|userId> | Approve the first pairing code or a pending request by user ID |
mercury telegram reject <userId> | Reject a pending access request |
mercury telegram remove <userId> | Remove an approved admin or member |
mercury telegram promote <userId> | Promote a member to admin |
mercury telegram demote <userId> | Demote an admin to member (at least one admin must remain) |
mercury telegram reset | Clear all Telegram access (admins, members, pending). Start fresh. |
Bot Commands Menu
Mercury registers 15 commands in Telegram's bot menu for quick access:
| Command | Description |
|---|---|
/start | Request access to this Mercury instance |
/help | Show Telegram-specific command reference |
/status | Config, budget, and uptime |
/progress | Live status for the current task |
/stop | Stop all agents and clear queue |
/budget | Token budget status and management |
/stream | Toggle text streaming on/off |
/memory | Second brain memory |
/permissions | Switch Ask Me / Allow All mode |
/models | List providers or switch AI model |
/code | Programming mode (plan / execute / off) |
/agents | List and manage sub-agents |
/bg | Background tasks |
/spotify | Spotify playback controls |
/unpair | Reset all Telegram access (admin only) |
Running /help on Telegram shows a clean, Telegram-formatted command reference with only Telegram-relevant commands — no CLI-only features like workspace IDE or progress views.
Real-Time Task Progress
During multi-step tasks, Mercury uses a single status card that updates in place. This keeps the chat clean — you see one message that shows what's happening, not a flood of separate updates.
How It Works
- Step 1 begins — Mercury creates a status card:
⚙️ Mercury working (step 1) - Steps progress — The same message is edited to show the latest steps with checkmarks
- Step 3+ (substantial task) — The status card is pinned to the top of the chat so you can always see progress without scrolling
- Notices — System messages like Mercury Autopilot warnings are folded into the status card instead of creating separate messages
- Task completes — The status card is unpinned and deleted. The AI response and completion banner appear as fresh messages
What the Status Card Looks Like
⚙️ Mercury working (step 5)
✅ read_file · src/index.ts
✅ edit_file · src/utils.ts
✅ run_command · npm test
✅ read_file · package.json
⏳ write_file · src/config.ts…
Single-Message Design
During an active task, no new messages are created in the chat. Everything is consolidated into the pinned status card:
- Tool progress — edited in place with a rolling window of the last 5 completed steps
- Autopilot warnings — shown as notice lines in the status card (last 3 notices)
- AI responses — deferred until the task completes, then sent as a clean message
- Permission prompts — shown as ephemeral inline keyboard messages, deleted after you respond
This means you never have to scroll up to find the progress indicator — it stays pinned at the top until the task is done.
Completion
When a substantial task finishes (3+ steps and 30+ seconds), Mercury sends a completion banner:
✅ Task complete (8 steps · 45s)
☿ claude-sonnet via anthropic · 12.4k tokens
Budget: ██████████░░░░░ 67% (67.2k / 100.0k)
✓ read_file · src/index.ts
✓ edit_file · src/utils.ts
✓ run_command · npm test
Permission Mode
At the start of each Telegram session, Mercury shows an inline keyboard to choose a permission mode:
- 🔒 Ask Me — Mercury asks before file writes, shell commands, and scope changes. Prompts appear as inline keyboards with Allow / Always / Deny buttons.
- ✅ Allow All — Auto-approve everything for this session. No interruptions.
Use /permissions at any time to switch modes. Choosing "Always" on any permission prompt flips to auto-approve for the rest of the session.
Ephemeral Messages
Permission prompts, loop-continuation prompts, and mode-selection cards are ephemeral — they're deleted automatically after you respond (or after a 2-minute timeout). This keeps the chat clean.
Features
| Feature | Description |
|---|---|
| Single status card | One message edited in place during multi-step tasks — no message clutter |
| Pinned progress | Status card pinned to chat top for tasks with 3+ steps |
| Text streaming | Real-time response editing with typing indicators (toggle with /stream) |
| File uploads | Photos, audio, video, and documents auto-detected and sent with the right API |
| HTML formatting | Markdown automatically converted to Telegram-compatible HTML |
| Inline keyboards | Permission and mode prompts shown as tappable buttons |
| Ephemeral prompts | Permission and mode cards auto-deleted after response |
| Completion banners | Token usage and budget stats for substantial tasks |
| Multi-user access | Organization model with admins and members |
| Bot commands menu | 15 commands registered in Telegram's bot menu for quick access |
Configuration
Telegram is set up during mercury doctor or initial onboarding. You need a bot token from @BotFather.
| Variable | Description | Default |
|---|---|---|
TELEGRAM_BOT_TOKEN | Bot token from @BotFather | — |
TELEGRAM_ENABLED | Enable/disable Telegram channel | false |
TELEGRAM_STREAMING | Enable real-time text streaming | true |
Type none as the bot token during mercury doctor to disable Telegram.