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, 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    │     /events      SSE to the proxy
│  · owns permissions  │     /permission  POST from the proxy
└──────────┬───────────┘
           │  SSE  ·  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 · edit_message
│  · holds the pin     │   one session per bot at a time
│  · forwards perms    │
└──────────┬───────────┘
           │  stdio MCP
           ▼
    Claude 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. 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 and/or OpenCode

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

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

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

Run it under tmux so the session survives the terminal:

tmux new -s mybot
tg claude mybot

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 opencode one is longer for two reasons. OpenCode does its own Telegram polling, so it stops our poller on the way in and restarts it on exit via a trap — that is how both runtimes share one token without 409ing each other. And it starts its own opencode serve on a kernel-assigned port, then kills it on exit: an OpenCode session works in the server's directory, so pointing several sessions at one long-lived server on a fixed port silently drops all of them into that server's folder instead of yours.

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 — so access.json and .env can't be talked out of the bot.

What the agent can do

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
runtimes/               one executable per runtime: claude, opencode, anon
server.ts               poller, gate, MCP HTTP server, permission UI
proxy.ts                stdio MCP server, tool implementations, pin, SSE 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
└── <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.