Telegram · Waterbrother

Prerequisites

Before you start

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

Shape

What Telegram is for right now

single-user remote control
status and runtime inspection
remote session switching
remote workspace switching
new project creation from Telegram
clean HTML formatting with edit-in-place replies

This is not group collaboration yet. That comes later, after single-user remote control and approvals are stable.

Setup

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

Pairing

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.

Remote Commands

Available in Telegram and the native bot menu

/help
/about
/state
/status
/runtime
/room
/members
/invites
/tasks
/room-runtime
/mode
/mode <chat|plan|execute>
/claim
/release
/invite <user-id> [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

Runtime Behavior

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 cwd, 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.

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

Permissions

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.

Shared Projects

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 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

This first slice is single-operator only. Shared project Telegram execution is gated on room mode execute. Owners administer room mode, membership, invites, and shared room runtime profile. Invited users can accept their own invite with /accept-invite. Owners and editors can claim the operator lock and assign tasks; any member can claim a task for themselves or add task comments. /room now shows the active executor surface, provider/model identity, pending invites, and task ownership summary. /about and /state expose Waterbrother's local self-awareness directly from the linked repo/runtime state. Assign, claim, and move operations also post a small Roundtable ownership notice back into Telegram. In groups, target the bot explicitly with a command, mention, or reply.

Intent Gating

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.

Troubleshooting

Symptom	Likely cause	What to check
`Telegram API getMe failed: Not Found`	Bad or revoked bot token	Verify the token with `curl https://api.telegram.org/botTOKEN/getMe` and make sure project config is not overriding user config.
No reply after DM	Gateway not running or user not paired	Check `waterbrother gateway status`, keep the gateway process running, and inspect `waterbrother gateway pairings`.
Telegram command changes cwd but work still uses the old repo	Live TUI host is not attached	Keep the TUI open, verify the gateway bridge is live, then retry the Telegram prompt. The fallback runner uses the saved remote session path but does not provide the same live visibility.
Remote run failed with JSON parse errors	Old Waterbrother build	Update to the latest npm release and restart the gateway.
Bot rejects your DM as unpaired	User id not approved yet	Approve locally with `waterbrother gateway pair telegram YOUR_TELEGRAM_USER_ID`.