telegram-msg

A simple tool for communicating with a Claude Code instance from your phone via Telegram. Two ways to use it:

1. As a Claude Code skill (-m "message" --wait) — Claude calls telegram-msg directly to send you a message and wait for your reply. Works anywhere, no tmux required.
2. As a tmux chat proxy (--start-relay) — A long-running bridge that lets you type into a tmux pane from Telegram. Run Claude Code inside tmux, start the relay, and optionally add a stop hook (--send-capture) so you get notified when Claude finishes.

It can also be used as a general-purpose CLI for sending Telegram messages via bot API.

Setup

1. Create a bot with @BotFather and get your BOT_TOKEN
2. Send a message to your bot, then get your CHAT_ID from: https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
3. Generate the config file and fill in your values:

npx telegram-msg --init   # creates .env.telegram in current directory

Usage

Send a message (-m)

telegram-msg -m "Hello from CLI"
telegram-msg -m "Check this out" --image /path/to/image.jpg
telegram-msg -m "Are you there?" --wait

When --wait is used, the bot polls for a reply and prints it to stdout. A timeout notice is appended to the message unless SHOW_TIMEOUT_NOTICE=false. Set ALWAYS_WAIT=true to wait on every message without the flag.

This command is designed to be used by Claude as a tool call. Add a skill file to your project so Claude can send you messages and wait for your response via Telegram:

.claude/skills/message/SKILL.md:

---
name: message
description: Send messages or photos to the user via Telegram. Use when you're done and wait for user to respond to your message.
---

Use `npx telegram-msg` for sending and receiving response:

```bash
cd .claude
npx telegram-msg -m "Your message here" --wait

# Photo with caption (use this for screenshots)
npx telegram-msg -m "Caption text" --image /path/to/image.png --wait
```

tmux relay (--start-relay)

Long-running bridge between Telegram and a tmux pane. Once started, any message you send to the bot from your Telegram client is typed into the tmux pane as keystrokes (with Enter appended by default). The following commands are recognized instead of being typed literally:

Capture commands — send these from Telegram to read pane output:

| Command | Description | |---|---| | ? | Capture last CAPTURE_LINES lines (default 20), with diff/dedup | | ?N | Capture last N lines, with diff/dedup | | ?? | Full raw capture (no diff/dedup) | | ??N | Raw capture of last N lines (no diff/dedup) |

Special keys — send these from Telegram to press a key (case-insensitive):

| Message | Key sent | |---|---| | esc | Escape | | tab | Tab | | shift+tab | Shift+Tab | | ctrl+c | Ctrl+C |

Only messages from CHAT_ID are accepted; all others are silently ignored. /start shows relay status.

Capture (--send-capture)

One-shot: captures the current tmux pane and sends it to Telegram. Long output is split into multiple messages. Designed for use as a Claude Code stop hook so you get notified on your phone when Claude finishes a task. Best used together with --start-relay — the relay lets you review the output and reply from Telegram without switching back to your terminal.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "npx telegram-msg --send-capture" }]
      }
    ]
  }
}

Configuration

Config is read from environment variables. If a .env.telegram file exists in the working directory it is loaded automatically, but it is not required — you can set the variables any other way.

| Variable | Default | Description | |---|---|---| | BOT_TOKEN | required | Bot token from @BotFather | | CHAT_ID | required | Target chat ID | | WAIT_TIMEOUT_MIN | 20 | Reply timeout in minutes | | ALWAYS_WAIT | false | Always wait for reply without --wait | | SHOW_TIMEOUT_NOTICE | true | Append timeout notice to messages | | TMUX_TARGET | 0 | tmux target pane (e.g. cloud:0.0) | | CAPTURE_LINES | 20 | Lines to capture for ? and --send-capture | | FULL_CAPTURE_LINES | 100 | Lines to capture for ?? (full raw capture) | | SEND_ENTER | 1 | Append Enter after relay keystrokes (0 to disable) | | SEND_ACK | 0 | Reply "sent" after each relay keystroke (1 to enable) |

CLI Reference

telegram-msg -m "message" [--image path] [--wait|-w]
telegram-msg --init
telegram-msg --start-relay
telegram-msg --send-capture
telegram-msg --remove-last-capture

License

MIT