- "content": "# 📱 Telegram Notifications Setup Guide\n\n## Overview\nGet real-time Telegram notifications when Claude Code finishes working, encounters long operations, or needs attention.\n\n## Available Hooks\n\n### 1. `telegram-notifications` - Basic Notifications\n- ✅ Notifies when main Claude Code session ends\n- 🎯 Notifies when subagent tasks complete\n- Simple timestamp information\n\n### 2. `telegram-detailed-notifications` - Advanced Session Tracking\n- 🚀 Session start notifications\n- ✅ Detailed completion notifications with duration\n- 💾 Memory usage information\n- 📁 Project name tracking\n\n### 3. `telegram-error-notifications` - Productivity Monitoring\n- ⚠️ Alerts for long-running Bash operations (>30 seconds)\n- 🔔 Notifications when Claude Code waits for user input\n- Helps catch stuck processes\n\n## Setup Instructions\n\n### Step 1: Create a Telegram Bot\n1. Message [@BotFather](https://t.me/BotFather) on Telegram\n2. Send `/newbot` command\n3. Follow instructions to create your bot\n4. Copy the **Bot Token** (looks like: `123456789:ABCD-EFGHijklmnop_qrstuvwxyz`)\n\n### Step 2: Get Your Chat ID\n1. Start a conversation with your bot\n2. Send any message to the bot\n3. Visit: `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`\n4. Find your **Chat ID** in the response (usually a number like `123456789`)\n\n### Step 3: Set Environment Variables\n\n#### Option A: Global Configuration (Recommended)\nAdd to your shell profile (`.bashrc`, `.zshrc`, or `.profile`):\n\n```bash\nexport TELEGRAM_BOT_TOKEN=\"123456789:ABCD-EFGHijklmnop_qrstuvwxyz\"\nexport TELEGRAM_CHAT_ID=\"123456789\"\n```\n\n#### Option B: Project-Specific Configuration\nAdd to your project's `.env` file or `.claude/settings.local.json`:\n\n```json\n{\n \"env\": {\n \"TELEGRAM_BOT_TOKEN\": \"123456789:ABCD-EFGHijklmnop_qrstuvwxyz\",\n \"TELEGRAM_CHAT_ID\": \"123456789\"\n }\n}\n```\n\n### Step 4: Install the Hook\n```bash\n# Basic notifications\nnpx claude-code-templates@latest --hook=automation/telegram-notifications\n\n# Detailed session tracking\nnpx claude-code-templates@latest --hook=automation/telegram-detailed-notifications\n\n# Productivity monitoring\nnpx claude-code-templates@latest --hook=automation/telegram-error-notifications\n```\n\n## Testing\nAfter setup, test the hook by running:\n```bash\n# This should trigger a notification when the command completes\necho \"Test complete\"\n```\n\n## Security Notes\n- ⚠️ **Never commit bot tokens to version control**\n- 🔒 Use `.claude/settings.local.json` for sensitive credentials\n- 🏢 For teams, consider using enterprise managed settings\n- 🔐 Regularly rotate bot tokens for security\n\n## Troubleshooting\n\n### No notifications received?\n1. Verify environment variables: `echo $TELEGRAM_BOT_TOKEN`\n2. Check bot token format (should contain `:`)\n3. Ensure you've messaged the bot first\n4. Verify chat ID is correct (numeric)\n\n### Bot responds with \"Forbidden\"?\n- The chat ID might be incorrect\n- You need to start a conversation with the bot first\n\n### Hook not triggering?\n- Verify hook is installed: check `.claude/settings.json`\n- Test with a simple command first\n- Check Claude Code version compatibility\n\n## Message Examples\n\n### Basic Notification\n```\n🤖 Claude Code finished working at 2025-01-15 14:30:45\n```\n\n### Detailed Notification\n```\n✅ Claude Code Session Completed\n📁 Project: my-awesome-project\n⏱️ Duration: 15m 32s\n💾 Memory Used: 245MB\n⏰ Finished: 14:30:45\n📅 Date: 2025-01-15\n```\n\n### Long Operation Alert\n```\n⚠️ Long Bash Operation\n⏱️ Duration: 2m 15s\n📁 Project: data-processing\n⏰ Time: 14:28:30\n```\n\n## Advanced Configuration\n\n### Custom Message Format\nYou can modify the hooks to customize message format:\n- Edit the `MESSAGE` variable in the hook command\n- Use HTML formatting with `parse_mode=HTML`\n- Add emojis and custom text\n\n### Group Notifications\n- Add the bot to a Telegram group\n- Use the group chat ID instead of personal chat ID\n- Perfect for team notifications\n\n### Multiple Projects\n- Use different bots for different projects\n- Set project-specific environment variables\n- Configure in `.claude/settings.local.json` per project",
0 commit comments