Claude Code Telegram Hooks

Claude Code Telegram Hooks

Control Claude Code from Telegram. Get notifications when Claude needs your attention — plans to approve and task completions.

Features

• IDE-first interaction — plans show in IDE immediately; if you don't respond within a configurable delay, a notification is sent to Telegram
• Completion notifications — get a Telegram message when Claude finishes a task, with any generated .md files attached
• Status line — see context window usage %, 5-hour API limit %, and time until reset right in your terminal

Example status line:

skills · 12% ctx · 22% limit · 3h46m before reset

**Note:** Tested on macOS only. Linux may work (uses `os.fork()`, `jq`, `curl`) but is untested. Windows is not supported.

Prerequisites

• macOS (uses os.fork() for background notifications and Keychain for OAuth in status line)
• Python 3 (pre-installed on macOS)
• jq — brew install jq
• Telegram bot — create one via @BotFather
• Claude Code with hooks support

Installation

1. Create your Telegram bot

1. Open @BotFather in Telegram
2. Send /newbot, follow the prompts
3. Copy the bot token
4. Send any message to your new bot
5. Get your chat ID:

   curl -s "https://api.telegram.org/bot/getUpdates" | jq '.result[-1].message.chat.id'

2. Copy scripts

# Clone the repo
git clone https://github.com/yourusername/claude-code-telegram-hooks.git
cd claude-code-telegram-hooks

# Copy hooks
cp hooks/* ~/.claude/hooks/
chmod +x ~/.claude/hooks/session-marker.sh ~/.claude/hooks/telegram-notify.sh ~/.claude/hooks/telegram_interactive.py

# Copy status line
mkdir -p ~/.claude/utils
cp utils/statusline.sh ~/.claude/utils/
chmod +x ~/.claude/utils/statusline.sh

3. Configure credentials

# Create .env file (never commit this!)
cat > ~/.claude/.env << 'EOF'
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_I