📚 Add comprehensive Settings and Hooks documentation to Docusaurus

davila7 · claude · davila7 · commit 3e71914d397f · 2025-08-14T09:02:01.000-04:00
- Added detailed Settings documentation (300+ lines) covering all configuration hierarchy levels - Added comprehensive Hooks documentation (400+ lines) with event-driven automation examples - Created Telegram notification hooks with complete setup guide - Updated overview page to include Settings and Hooks as new component types - Updated sidebar navigation to include new documentation sections - Documented installation location selection for both Settings and Hooks - Added security guidelines, troubleshooting, and best practices 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/cli-tool/components/hooks/automation/TELEGRAM_SETUP.md b/cli-tool/components/hooks/automation/TELEGRAM_SETUP.md
@@ -0,0 +1,143 @@
+# 📱 Telegram Notifications Setup Guide
+
+## Overview
+Get real-time Telegram notifications when Claude Code finishes working, encounters long operations, or needs attention.
+
+## Available Hooks
+
+### 1. `telegram-notifications` - Basic Notifications
+- ✅ Notifies when main Claude Code session ends
+- 🎯 Notifies when subagent tasks complete
+- Simple timestamp information
+
+### 2. `telegram-detailed-notifications` - Advanced Session Tracking
+- 🚀 Session start notifications
+- ✅ Detailed completion notifications with duration
+- 💾 Memory usage information
+- 📁 Project name tracking
+
+### 3. `telegram-error-notifications` - Productivity Monitoring
+- ⚠️ Alerts for long-running Bash operations (>30 seconds)
+- 🔔 Notifications when Claude Code waits for user input
+- Helps catch stuck processes
+
+## Setup Instructions
+
+### Step 1: Create a Telegram Bot
+1. Message [@BotFather](https://t.me/BotFather) on Telegram
+2. Send `/newbot` command
+3. Follow instructions to create your bot
+4. Copy the **Bot Token** (looks like: `123456789:ABCD-EFGHijklmnop_qrstuvwxyz`)
+
+### Step 2: Get Your Chat ID
+1. Start a conversation with your bot
+2. Send any message to the bot
+3. Visit: `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`
+4. Find your **Chat ID** in the response (usually a number like `123456789`)
+
+### Step 3: Set Environment Variables
+
+#### Option A: Global Configuration (Recommended)
+Add to your shell profile (`.bashrc`, `.zshrc`, or `.profile`):
+
+```bash
+export TELEGRAM_BOT_TOKEN="123456789:ABCD-EFGHijklmnop_qrstuvwxyz"
+export TELEGRAM_CHAT_ID="123456789"
+```
+
+#### Option B: Project-Specific Configuration
+Add to your project's `.env` file or `.claude/settings.local.json`:
+
+```json
+{
+  "env": {
+    "TELEGRAM_BOT_TOKEN": "123456789:ABCD-EFGHijklmnop_qrstuvwxyz",
+    "TELEGRAM_CHAT_ID": "123456789"
+  }
+}
+```
+
+### Step 4: Install the Hook
+```bash
+# Basic notifications
+npx claude-code-templates@latest --hook=automation/telegram-notifications
+
+# Detailed session tracking
+npx claude-code-templates@latest --hook=automation/telegram-detailed-notifications
+
+# Productivity monitoring
+npx claude-code-templates@latest --hook=automation/telegram-error-notifications
+```
+
+## Testing
+After setup, test the hook by running:
+```bash
+# This should trigger a notification when the command completes
+echo "Test complete"
+```
+
+## Security Notes
+- ⚠️ **Never commit bot tokens to version control**
+- 🔒 Use `.claude/settings.local.json` for sensitive credentials
+- 🏢 For teams, consider using enterprise managed settings
+- 🔐 Regularly rotate bot tokens for security
+
+## Troubleshooting
+
+### No notifications received?
+1. Verify environment variables: `echo $TELEGRAM_BOT_TOKEN`
+2. Check bot token format (should contain `:`)
+3. Ensure you've messaged the bot first
+4. Verify chat ID is correct (numeric)
+
+### Bot responds with "Forbidden"?
+- The chat ID might be incorrect
+- You need to start a conversation with the bot first
+
+### Hook not triggering?
+- Verify hook is installed: check `.claude/settings.json`
+- Test with a simple command first
+- Check Claude Code version compatibility
+
+## Message Examples
+
+### Basic Notification
+```
+🤖 Claude Code finished working at 2025-01-15 14:30:45
+```
+
+### Detailed Notification
+```
+✅ Claude Code Session Completed
+📁 Project: my-awesome-project
+⏱️ Duration: 15m 32s
+💾 Memory Used: 245MB
+⏰ Finished: 14:30:45
+📅 Date: 2025-01-15
+```
+
+### Long Operation Alert
+```
+⚠️ Long Bash Operation
+⏱️ Duration: 2m 15s
+📁 Project: data-processing
+⏰ Time: 14:28:30
+```
+
+## Advanced Configuration
+
+### Custom Message Format
+You can modify the hooks to customize message format:
+- Edit the `MESSAGE` variable in the hook command
+- Use HTML formatting with `parse_mode=HTML`
+- Add emojis and custom text
+
+### Group Notifications
+- Add the bot to a Telegram group
+- Use the group chat ID instead of personal chat ID
+- Perfect for team notifications
+
+### Multiple Projects
+- Use different bots for different projects
+- Set project-specific environment variables
+- Configure in `.claude/settings.local.json` per project
diff --git a/cli-tool/components/hooks/automation/telegram-detailed-notifications.json b/cli-tool/components/hooks/automation/telegram-detailed-notifications.json
@@ -0,0 +1,26 @@
+{
+  "description": "Send detailed Telegram notifications with session information when Claude Code finishes. Includes working directory, session duration, and system info. Requires TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID environment variables.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [[ -n \"$TELEGRAM_BOT_TOKEN\" && -n \"$TELEGRAM_CHAT_ID\" ]]; then echo \"$(date +%s)\" > ~/.claude/session_start.tmp; PROJECT_DIR=\"$(basename \"$(pwd)\")\" && MESSAGE=\"🚀 <b>Claude Code Session Started</b>%0A📁 Project: $PROJECT_DIR%0A⏰ Time: $(date '+%H:%M:%S')%0A📅 Date: $(date '+%Y-%m-%d')\"; curl -s -X POST \"https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage\" -d \"chat_id=$TELEGRAM_CHAT_ID\" -d \"text=$MESSAGE\" -d \"parse_mode=HTML\" >/dev/null 2>&1; fi"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [[ -n \"$TELEGRAM_BOT_TOKEN\" && -n \"$TELEGRAM_CHAT_ID\" ]]; then END_TIME=\"$(date +%s)\"; if [[ -f ~/.claude/session_start.tmp ]]; then START_TIME=\"$(cat ~/.claude/session_start.tmp)\"; DURATION=\"$((END_TIME - START_TIME))\"; MINUTES=\"$((DURATION / 60))\"; SECONDS=\"$((DURATION % 60))\"; DURATION_TEXT=\"${MINUTES}m ${SECONDS}s\"; rm -f ~/.claude/session_start.tmp; else DURATION_TEXT=\"Unknown\"; fi; PROJECT_DIR=\"$(basename \"$(pwd)\")\"; MEMORY_MB=\"$(ps -o rss= -p $$ 2>/dev/null | awk '{print int($1/1024)}' || echo 'N/A')\"; MESSAGE=\"✅ <b>Claude Code Session Completed</b>%0A📁 Project: $PROJECT_DIR%0A⏱️ Duration: $DURATION_TEXT%0A💾 Memory Used: ${MEMORY_MB}MB%0A⏰ Finished: $(date '+%H:%M:%S')%0A📅 Date: $(date '+%Y-%m-%d')\"; curl -s -X POST \"https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage\" -d \"chat_id=$TELEGRAM_CHAT_ID\" -d \"text=$MESSAGE\" -d \"parse_mode=HTML\" >/dev/null 2>&1 || echo \"Failed to send detailed Telegram notification\"; else echo \"⚠️ Detailed Telegram notification skipped: Set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID\"; fi"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/cli-tool/components/hooks/automation/telegram-error-notifications.json b/cli-tool/components/hooks/automation/telegram-error-notifications.json
@@ -0,0 +1,37 @@
+{
+  "description": "Send Telegram notifications when Claude Code encounters long-running operations or when tools take significant time. Helps monitor productivity and catch potential issues. Requires TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID environment variables.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [[ -n \"$TELEGRAM_BOT_TOKEN\" && -n \"$TELEGRAM_CHAT_ID\" ]]; then echo \"$(date +%s)\" > ~/.claude/bash_start.tmp; fi"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [[ -n \"$TELEGRAM_BOT_TOKEN\" && -n \"$TELEGRAM_CHAT_ID\" && -f ~/.claude/bash_start.tmp ]]; then END_TIME=\"$(date +%s)\"; START_TIME=\"$(cat ~/.claude/bash_start.tmp)\"; DURATION=\"$((END_TIME - START_TIME))\"; rm -f ~/.claude/bash_start.tmp; if [[ $DURATION -gt 30 ]]; then MINUTES=\"$((DURATION / 60))\"; SECONDS=\"$((DURATION % 60))\"; MESSAGE=\"⚠️ <b>Long Bash Operation</b>%0A⏱️ Duration: ${MINUTES}m ${SECONDS}s%0A📁 Project: $(basename \"$(pwd)\")%0A⏰ Time: $(date '+%H:%M:%S')\"; curl -s -X POST \"https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage\" -d \"chat_id=$TELEGRAM_CHAT_ID\" -d \"text=$MESSAGE\" -d \"parse_mode=HTML\" >/dev/null 2>&1; fi; fi"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [[ -n \"$TELEGRAM_BOT_TOKEN\" && -n \"$TELEGRAM_CHAT_ID\" ]]; then MESSAGE=\"🔔 <b>Claude Code Notification</b>%0A📁 Project: $(basename \"$(pwd)\")%0A⏰ Time: $(date '+%H:%M:%S')%0A💬 Status: Waiting for user input or permission\"; curl -s -X POST \"https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage\" -d \"chat_id=$TELEGRAM_CHAT_ID\" -d \"text=$MESSAGE\" -d \"parse_mode=HTML\" >/dev/null 2>&1; fi"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/cli-tool/components/hooks/automation/telegram-notifications.json b/cli-tool/components/hooks/automation/telegram-notifications.json
@@ -0,0 +1,25 @@
+{
+  "description": "Send Telegram notifications when Claude Code finishes working. Requires TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID environment variables. Get bot token from @BotFather, get chat ID by messaging the bot and visiting https://api.telegram.org/bot<TOKEN>/getUpdates",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [[ -n \"$TELEGRAM_BOT_TOKEN\" && -n \"$TELEGRAM_CHAT_ID\" ]]; then MESSAGE=\"🤖 Claude Code finished working at $(date '+%Y-%m-%d %H:%M:%S')\"; curl -s -X POST \"https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage\" -d \"chat_id=$TELEGRAM_CHAT_ID\" -d \"text=$MESSAGE\" -d \"parse_mode=HTML\" >/dev/null 2>&1 || echo \"Failed to send Telegram notification\"; else echo \"⚠️ Telegram notification skipped: Set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID environment variables\"; fi"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [[ -n \"$TELEGRAM_BOT_TOKEN\" && -n \"$TELEGRAM_CHAT_ID\" ]]; then MESSAGE=\"🎯 Claude Code subagent completed task at $(date '+%Y-%m-%d %H:%M:%S')\"; curl -s -X POST \"https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage\" -d \"chat_id=$TELEGRAM_CHAT_ID\" -d \"text=$MESSAGE\" -d \"parse_mode=HTML\" >/dev/null 2>&1 || echo \"Failed to send Telegram notification\"; else echo \"⚠️ Telegram notification skipped: Set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID environment variables\"; fi"
+          }
+        ]
+      }
+    ]
+  }
+}
