Telegram

Before you start

1. Create a Telegram bot with @BotFather.
2. Copy the bot token.
3. Know your Telegram numeric user id.
4. Plan to keep pairing in manual mode first.

What Telegram is for right now

• single-user remote control
• status, runtime, and live-terminal inspection
• remote session switching
• remote workspace switching
• new project creation from Telegram
• shared-room execution and review routing
• clean HTML formatting with edit-in-place replies

Telegram now supports real Roundtable collaboration: participant and agent state, executor and reviewer roles, live terminal visibility, runtime split checks, and room-native review actions.

Terminal commands

waterbrother config set-json channels '{"telegram":{"enabled":true,"botToken":"YOUR_BOT_TOKEN","pairingMode":"manual","allowedUserIds":[]}}' --scope user
waterbrother config set-json gateway '{"enabled":true,"controlMode":"single-user","startupChannels":["telegram"]}' --scope user
waterbrother channels status --json --skip-onboarding
waterbrother gateway status --json --skip-onboarding
waterbrother gateway run telegram

Explicit local approval

Unknown Telegram DMs do not get control automatically. The first DM creates a pending pairing request in Waterbrother’s local gateway state.

waterbrother gateway pairings
waterbrother gateway pair telegram YOUR_TELEGRAM_USER_ID
waterbrother gateway unpair telegram YOUR_TELEGRAM_USER_ID

Project config overrides user config. If you have channel config in both places, make sure you know which scope is active before debugging pairing or tokens.

Available in Telegram and the native bot menu

• /help
• /about
• /state
• /run <prompt>
• /status
• /whoami
• /people
• /pair <user-id|@username>
• /project
• /project use <path|name>
• /project new <name>
• /project share
• /runtime
• /room
• /events
• /members
• /invites
• /tasks
• /room-runtime
• /mode
• /mode <chat|plan|execute>
• /claim
• /release
• /invite <user-id|@username> [owner|editor|observer]
• /accept-invite <invite-id>
• /approve-invite <invite-id>
• /reject-invite <invite-id>
• /remove-member <user-id>
• /task add <text>
• /task assign <id> <member-id>
• /task claim <id>
• /task move <id> <open|active|blocked|done>
• /task comment <id> <text>
• /task history <id>
• /cwd
• /use <path>
• /desktop
• /new-project <name>
• /sessions
• /resume <id>
• /new
• /clear

What a normal message does

Any non-command DM is routed into the linked Waterbrother session. If the Waterbrother TUI is open, the message is injected into that live session and the work is visible in the terminal in real time. Workspace changes made from Telegram follow the same live session too, so the paired Telegram user can switch projects, rebind the current chat with /project share, use Desktop, or create a new Desktop project before running the next task. If no live TUI host is attached, Waterbrother falls back to the remote session runner.

The same project, pairing, shared-room, and execution actions can also be triggered conversationally. Requests like “share this project in this chat”, “pair Austin”, “switch to TelegramTest”, “add Austin as editor”, or “make a simple product page for this project” resolve against the current Waterbrother project state instead of requiring exact slash-command syntax. In a bound shared room, owner requests like “add Austin as editor” pair the person if needed and add them directly to the project. State questions like “is Austin paired?”, “is Austin in the project?”, “who is in the room?”, “which terminals are live?”, “what is the model conflict?”, and “compare executor and reviewer” answer directly from live room and agent state. /run <prompt> still works, but directly addressed execution in groups now runs as long as the room is in execute mode and the operator lock is held.

In Telegram groups, Waterbrother only responds when directly targeted: slash commands, @botname mentions, or replies to a bot message.

Same operator, same authority

A paired Telegram user is treated as the same operator as the terminal user when the live TUI bridge is attached. The only reduced path is the fallback remote runner, which still uses approval=never when no live TUI host is available.

First collaboration primitives

Shared projects now have machine state in .waterbrother/shared.json and a human collaboration file in ROUNDTABLE.md. In Telegram, a shared project can expose room status, pending invites, member roles, and a single active-operator lock with /room, /members, /invites, /mode, /claim, and /release.

waterbrother project share
waterbrother room status
waterbrother room events
waterbrother room members
waterbrother room invite 8331997434 editor Phillip
waterbrother room invites
waterbrother room invite accept inv_ab12cd
waterbrother room task add "Ship Telegram group tasks"
waterbrother room task assign rt_ab12cd 8331997434
waterbrother room task comment rt_ab12cd "Need owner review"
waterbrother room task history rt_ab12cd
waterbrother room runtime review-anthropic
waterbrother room tasks
waterbrother room mode execute
waterbrother room claim
waterbrother room release

Shared project Telegram execution is still gated on room mode execute, but the room now tracks more than a single lock. Owners administer room mode, membership, invites, and shared room runtime profile. The room also tracks participants, agents, live terminals, selected executor, reviewer role, verifier role, runtime split, blocking review state, blocking verification state, latest reviewer outcome, latest verification outcome, and verifier execution environment. If the selected executor is live, Telegram work is routed there. If a blocking reviewer is live, the room can send review there, get a structured outcome back, and then accept reviewer concerns, override the reviewer, or switch executor to the reviewer conversationally. If verification mode is auto or blocking, Telegram now runs verification after execution and can pause later execution until the room says rerun verification or override verification.

Shared Telegram group flow

1. Create or pick a Telegram group for the collaborators.
2. Add the Waterbrother bot to that group.
3. Add the human teammates to the same Telegram group using normal Telegram controls.
4. In the repo, run waterbrother project share or use /project share in Telegram.
5. Have teammates speak once in the room. Owners can use /people to see visible participants.
6. Use owner conversational requests like “add Austin as editor” or “pair Austin” instead of relying on raw ids first.
7. Use /room, /events, and /mode execute when the group is ready to act.
8. Use conversational mediation like “have Austin’s bot be reviewer”, “make this terminal the verifier”, “have Phillip’s bot take execution”, “verification mode blocking”, or “compare executor and reviewer” once more than one terminal is live.

Group membership, room membership, participant state, and agent state are still separate internally, but trusted-room owner actions now bridge most of that gap directly from the chat.

Group messages are classified before execution

In Telegram groups, even directly targeted messages do not all execute. Waterbrother classifies them as chat, planning, or execution. Only explicit execution requests run the live session. Planning and brainstorming messages stay non-executing and should be converted into shared tasks when needed.

In shared plan mode, targeted messages starting with task: or todo: are captured directly into the shared task queue. Targeted product/project questions like “what is Roundtable?” are answered directly from local repo state instead of falling back to a generic planner message. In groups, explicit execution should use /run <prompt>.

Start with the integrations overview, then use Telegram onboarding for the shorter setup path or Roundtable for the shared-room collaboration model.