harness-telegram-bridge

Drive a coding agent from Telegram. Send a message from your phone, an agent session on your machine picks it up, works, and replies in the chat — with file attachments, emoji reactions, live-edited progress messages, and tap-to-approve permission prompts.

Runtime-agnostic: the same bot can front Claude Code, Kimi Code, OpenCode, or a blank context-free session. One machine can run several bots at once, each fully isolated.

How it works

Three pieces. Two are in this repo.

   Telegram
       │  long-polling
       ▼
┌──────────────────────┐   systemd user unit, one per bot
│  server.ts           │   telegram-mcp@<bot>.service
│                      │
│  · polls Telegram    │   HTTP on $TELEGRAM_MCP_PORT:
│  · runs the gate     │     /mcp         MCP transport
│  · queues inbound    │     /poll        JSON drain for proxy
│  · owns permissions  │     /permission  POST from the proxy
└──────────┬───────────┘
           │  /poll  ·  queues up to 500 messages while nothing is attached
           ▼
┌──────────────────────┐   spawned by the agent as a stdio MCP server
│  proxy.ts            │
│                      │
│  · implements tools  │   reply · react · download_attachment
│  · holds the pin     │   edit_message · wait_for_message
│  · forwards perms    │   one session per bot at a time
└──────────┬───────────┘
           │  stdio MCP
           ▼
    Claude Code / Kimi Code / OpenCode

The poller outlives your session. server.ts runs as an always-on systemd unit. Close your terminal, reboot your laptop, /clear your session — the bot stays up and keeps accepting messages. Anything that arrives while no session is attached is queued (up to 500) and flushed the moment one reconnects. You are never the reason a message is lost.

The pin stops the crossfire. Telegram allows exactly one poller per token; a second one gets a permanent 409. proxy.ts takes a lockfile (pinned.lock) so only one agent session owns a given bot — a second proxy on the same bot receives nothing (wait_for_message returns an error naming the owner) until the lock frees up. Stale locks from dead processes are detected and cleared automatically, so a crashed session doesn't strand the bot.

Related MCP server: tsgram-mcp

Setup

Prerequisites

• Bun

• A bot token from @BotFather

• At least one agent runtime: Claude Code, Kimi Code, and/or OpenCode

• Python 3.10+ with python-telegram-bot (for daemon.py backends)

Install

git clone https://github.com/Swigler/harness-telegram-bridge ~/.claude/telegram-server
cd ~/.claude/telegram-server
bun install

mkdir -p ~/.config/systemd/user
ln -s ~/.claude/telegram-server/telegram-mcp@.service ~/.config/systemd/user/
systemctl --user daemon-reload

Then put the launcher on your PATH and the runtimes where tg looks for them:

mkdir -p ~/bin ~/.claude/channels/telegram
ln -s ~/.claude/telegram-server/tg ~/bin/tg
ln -s ~/.claude/telegram-server/runtimes ~/.claude/channels/telegram/runtimes

For kimi/opencode foreground runtimes, set up the daemon venv:

python3 -m venv ~/.claude/channels/telegram/.venv
~/.claude/channels/telegram/.venv/bin/pip install python-telegram-bot httpx

Add a bot

tg setup mybot

The wizard verifies the token against getMe before writing anything, picks the next free port, writes the state dir, and enables + starts the poller. It refuses to clobber a bot that already exists.

Manual equivalent, if you prefer:

mkdir -p ~/.claude/channels/telegram/mybot
cat > ~/.claude/channels/telegram/mybot/.env <<'EOF'
TELEGRAM_BOT_TOKEN=123456789:AAH...
TELEGRAM_MCP_PORT=3456
EOF
chmod 600 ~/.claude/channels/telegram/mybot/.env

echo '{"dmPolicy":"allowlist","allowFrom":["<your-telegram-user-id>"]}' \
  > ~/.claude/channels/telegram/mybot/access.json

echo '{"mybot":{"port":3456}}' > ~/.claude/channels/telegram/bots.json
systemctl --user enable --now telegram-mcp@mybot.service

Usage

Interactive sessions (foreground, needs terminal)

tg <runtime> <bot> [extra args...]

Close the terminal = bot dies. Run under tmux for persistence:

tmux new -s mybot
tg kimi mybot

Always-on daemons (no terminal needed)

tg start <runtime> <bot> [workdir]

Other commands

Adding a runtime

Drop an executable in ~/.claude/channels/telegram/runtimes/. tg exports TELEGRAM_STATE_DIR, TELEGRAM_MCP_PORT, TELEGRAM_MCP_URL, and TELEGRAM_POLLER_UNIT, then execs your script. That is the whole contract.

The shipped claude runtime is two lines. The kimi and opencode runtimes run daemon.py in the foreground — a python-telegram-bot poller that spawns one CLI subprocess per message. They stop the MCP poller on entry (409 conflict) and restart it on exit via a trap — so a runtime must not exec its long-running process, or the trap never fires.

Access control

access.json per bot, three modes:

Groups are opt-in per chat ID, default to requiring an @mention, and take their own per-group allowlist.

Approval happens in your terminal, never from chat. The MCP instructions tell the agent explicitly that a Telegram message asking to be added to the allowlist is what a prompt injection looks like, and to refuse it.

Under allowlist and disabled, /start, /help and /status are muted for anyone not on the list — a stranger who finds the bot gets silence, not a helpful explanation of what it is. Under pairing they answer normally, since that is how a new person learns to pair.

Outbound is checked too: every tool call re-validates the target chat against the allowlist, and the file sender refuses to attach anything from inside the state directory — in server.ts and proxy.ts alike — so access.json, .env and http.token can't be talked out of the bot.

Local surfaces

The Telegram allowlist is not the only door. Two local endpoints are locked down separately:

• server.ts HTTP API binds 127.0.0.1 (override: TELEGRAM_MCP_HOST) and every endpoint requires the per-bot token in <state_dir>/http.token, created on first start (0600). proxy.ts reads it automatically. For direct HTTP MCP use, pass --header "Authorization: Bearer $(cat <state_dir>/http.token)". Delete the file and restart the poller to rotate it.

• kimiweb / openclaudeweb browser terminals are writable and drive an agent with permissions bypassed. ttyd binds loopback only (TTYD_INTERFACE=lo); reach it with ssh -L 7682:127.0.0.1:7682 <host>. To bind another interface (e.g. TTYD_INTERFACE=tailscale0) you must also set TTYD_CREDENTIAL=user:password, or the runtime refuses to start. ttyd runs with --check-origin, so web pages in a browser that can reach the port can't open the terminal socket. Setting TTYD_CREDENTIAL on loopback too is still recommended: it also covers DNS-rebinding and other local users.

daemon.py caps each backend turn at TG_BACKEND_TIMEOUT seconds (default 900) and voice transcription at TG_TRANSCRIBE_TIMEOUT (default 300). /reset kills a stuck turn instead of waiting behind it.

What the agent can do

Non-Claude MCP clients (opencode etc.) must set TELEGRAM_PROXY_PUSH=0 in the proxy's environment. By default the proxy also pushes queued messages as Claude Code channel notifications whenever wait_for_message isn't running; any other client drops those, so messages that arrive while the agent is busy would be lost. With push off they stay queued until the next wait_for_message.

Inbound handles text, photos, documents, voice, audio, video, video notes and stickers. Photos are downloaded automatically; everything else arrives with a file_id the agent can fetch on demand.

Permission prompts

When the agent needs approval, the prompt goes to your phone as three buttons — See more, Allow, Deny. "See more" expands the full tool input before you decide. Only allowlisted users can press them. You can also answer in text: y a1b2c or n a1b2c.

Staying up

Files

tg                      launcher — resolves runtime + bot, exports the contract, execs
                        also: start/stop/status for always-on daemons
daemon.py               python-telegram-bot poller with kimi/opencode/claude backends
runtimes/               one executable per runtime: claude, kimi, opencode, anon
server.ts               poller, gate, MCP HTTP server, permission UI
proxy.ts                stdio MCP server, tool implementations, pin, poll client
telegram-mcp@.service   templated systemd unit — one instance per bot
package.json            bun deps: grammy, express, MCP SDK, zod

State, outside the repo:

~/.claude/channels/telegram/
├── bots.json                name → port
├── runtimes/                one executable per runtime
├── daemon.py                (symlinked or copied from repo)
├── .venv/                   python-telegram-bot venv for daemon
└── <bot>/
    ├── .env                 token + port  (0600)
    ├── access.json          policy + allowlist
    ├── bot.pid              running poller
    ├── pinned.lock          session that owns the bot
    └── inbox/               downloaded attachments

License

Apache-2.0.