Claude Telegram Notifier

Get Telegram notifications when Claude Code needs your input, and reply directly from Telegram.

Features

• Notifications: Receive Telegram messages when Claude Code asks a question
• Reply from Telegram: Send responses directly from Telegram to your Claude Code session
• Auto-detection: Automatically finds your Claude Code tmux session
• Cross-platform: Works on Linux (systemd) and macOS (launchd)

Prerequisites

• Node.js 18+
• tmux (for receiving Telegram replies in Claude Code)
• curl, jq (for shell scripts)
• A Telegram bot (create one via @BotFather)

Installation

npm

npm install -g claude-telegram-notifier

From source

git clone https://github.com/yourusername/claude-telegram-notifier.git
cd claude-telegram-notifier
npm install
npm link

Quick Start

1. Run the setup wizard:

   claude-telegram-notifier setup

2. Start Claude Code in tmux:

   tmux new-session -s claude
   claude

3. That's it! When Claude asks a question, you'll get a Telegram notification.

Commands

| Command | Description | |---------|-------------| | setup | Interactive setup wizard | | status | Show configuration and poller status | | start-poller | Start the Telegram polling daemon | | stop-poller | Stop the Telegram polling daemon | | enable-service | Enable auto-start on login | | disable-service | Disable auto-start | | install-hooks | Install Claude Code hooks | | uninstall-hooks | Remove Claude Code hooks | | test | Send a test notification |

Configuration

Configuration is stored in ~/.config/claude-telegram-notifier/config.json:

{
  "telegramToken": "your-bot-token",
  "telegramChatId": "your-chat-id",
  "tmuxTarget": "",
  "pollInterval": 2
}

Environment Variables

Environment variables override the config file:

| Variable | Description | |----------|-------------| | TELEGRAM_TOKEN | Telegram bot token | | TELEGRAM_CHAT_ID | Your Telegram chat ID | | TMUX_TARGET | Tmux target (e.g., main:0.0) | | POLL_INTERVAL | Polling interval in seconds (default: 2) |

How It Works

1. Claude Code hooks: When Claude Code calls AskUserQuestion, a hook runs telegram-notify.sh which sends you a Telegram message.

2. Telegram poller: The telegram-poller.sh script polls Telegram for replies and injects them into your tmux session running Claude Code.

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
│   Claude Code   │────>│ telegram-notify  │────>│  Telegram   │
│  (in tmux)      │     │     (hook)       │     │     Bot     │
└─────────────────┘     └──────────────────┘     └─────────────┘
        ▲                                               │
        │                                               │
        │           ┌──────────────────┐               │
        └───────────│ telegram-poller  │<──────────────┘
                    │    (daemon)      │
                    └──────────────────┘

Getting Your Telegram Credentials

Bot Token

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the instructions
3. Copy the bot token provided

Chat ID

1. Start a chat with your new bot
2. Send any message to the bot
3. Visit https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
4. Find "chat":{"id":123456789} in the response

Or simply message @userinfobot and it will tell you your ID.

Troubleshooting

Poller not detecting tmux session

Set the tmux target explicitly:

# In config file
{
  "tmuxTarget": "claude:0.0"
}

# Or via environment
export TMUX_TARGET="claude:0.0"

Notifications not sending

1. Check configuration: claude-telegram-notifier status
2. Test connection: claude-telegram-notifier test
3. Verify hooks are installed: Check ~/.claude/settings.json

Replies not reaching Claude

1. Ensure Claude Code is running in tmux
2. Check poller is running: claude-telegram-notifier status
3. Check poller logs: journalctl --user -u claude-telegram-poller -f

License

MIT