claudeguide-engineer 1.14.8

package/.claude/hooks/discord-hook-setup.md

@@ -0,0 +1,440 @@
+# Discord Notification Hook Setup
+
+## Overview
+
+The Discord hook (`send-discord.sh`) sends rich embedded messages to a Discord channel when Claude Code completes implementation tasks. Messages include session time, project info, and task summaries.
+
+## Features
+
+- Rich embedded messages with custom formatting
+- Session timestamp tracking
+- Project name and location display
+- Custom message content
+- Automatic .env file loading
+
+## Setup Instructions
+
+### 1. Create Discord Webhook
+
+1. Open your Discord server
+2. Navigate to **Server Settings** → **Integrations** → **Webhooks**
+3. Click **"New Webhook"**
+4. Configure webhook:
+   - **Name:** `Claude Code Bot` (or your preference)
+   - **Channel:** Select your target notification channel
+5. Click **"Copy Webhook URL"**
+   - Format: `https://discord.com/api/webhooks/WEBHOOK_ID/WEBHOOK_TOKEN`
+
+### 2. Configure Environment Variables
+
+Environment variables are loaded with this priority (highest to lowest):
+
+1. **process.env** - System/shell environment variables
+2. **.claude/.env** - Project-level Claude configuration
+3. **.claude/hooks/.env** - Hook-specific configuration
+
+**Option A: Project Root `.env`** (recommended):
+
+```bash
+DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN
+```
+
+**Option B: `.claude/.env`** (project-level override):
+
+```bash
+DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN
+```
+
+**Option C: `.claude/hooks/.env`** (hook-specific):
+
+```bash
+DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN
+```
+
+**Example:**
+
+```bash
+DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/1234567890/AbCdEfGhIjKlMnOpQrStUvWxYz
+```
+
+See `.env.example` files for templates.
+
+### 3. Secure Your Configuration
+
+Add `.env` to `.gitignore` to prevent committing webhook URLs:
+
+```bash
+# .gitignore
+.env
+.env.*
+```
+
+### 4. Make Script Executable
+
+```bash
+chmod +x .claude/hooks/send-discord.sh
+```
+
+### 5. Verify Setup
+
+Test the hook with a simple message:
+
+```bash
+./.claude/hooks/send-discord.sh 'Test notification from Claude Code'
+```
+
+**Expected output:**
+
+```
+Loading .env file...
+✅ Environment loaded, DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/12...
+✅ Discord notification sent
+```
+
+Check your Discord channel for the test message.
+
+## Usage
+
+### Manual Invocation
+
+Send a notification with a custom message:
+
+```bash
+./.claude/hooks/send-discord.sh 'Task completed: Added user authentication feature'
+```
+
+**With multi-line messages:**
+
+```bash
+./.claude/hooks/send-discord.sh 'Implementation Complete
+
+✅ Added user authentication
+✅ Created login/signup forms
+✅ Integrated JWT tokens
+✅ All tests passing'
+```
+
+**Important:** Escape special characters:
+
+```bash
+./.claude/hooks/send-discord.sh 'Fixed bug in user'\''s profile page'
+```
+
+### Automated Usage (Claude Code Workflow)
+
+Claude automatically calls this script when completing implementations. This is configured in `.claude/workflows/development-rules.md`:
+
+```markdown
+- When you finish the implementation, send a full summary report to Discord channel
+  with `./.claude/hooks/send-discord.sh 'Your message here'` script
+```
+
+Claude will automatically:
+
+1. Complete the implementation task
+2. Generate a summary report
+3. Send it to Discord using this hook
+
+### Integration Examples
+
+**From bash scripts:**
+
+```bash
+#!/bin/bash
+# deploy.sh
+
+if npm run build && npm run test; then
+    ./.claude/hooks/send-discord.sh '✅ Build and tests passed - ready to deploy'
+else
+    ./.claude/hooks/send-discord.sh '❌ Build or tests failed - deployment blocked'
+fi
+```
+
+**From npm scripts (package.json):**
+
+```json
+{
+  "scripts": {
+    "deploy": "npm run build && npm run test && ./.claude/hooks/send-discord.sh '✅ Deployment successful'",
+    "notify": "./.claude/hooks/send-discord.sh"
+  }
+}
+```
+
+## Message Format
+
+Discord messages are sent as rich embeds with the following structure:
+
+**Embed Components:**
+
+- **Title:** 🤖 Claude Code Session Complete
+- **Description:** Your custom message content
+- **Color:** Purple (#57F287)
+- **Timestamp:** Automatic UTC timestamp
+- **Footer:** Project name and directory
+
+**Embedded Fields:**
+
+- ⏰ **Session Time:** Local time when notification sent
+- 📂 **Project:** Current project directory name
+
+**Example Discord Message:**
+
+```
+╔═══════════════════════════════╗
+║ 🤖 Claude Code Session Complete
+╠═══════════════════════════════╣
+║ Implementation Complete
+║
+║ ✅ Added user authentication
+║ ✅ Created login/signup forms
+║ ✅ Integrated JWT tokens
+║ ✅ All tests passing
+╠═══════════════════════════════╣
+║ ⏰ Session Time: 14:30:45
+║ 📂 Project: claudeGuide-engineer
+╠═══════════════════════════════╣
+║ DevPocket API • claudeGuide-engineer
+║ Today at 14:30
+╚═══════════════════════════════╝
+```
+
+## Troubleshooting
+
+### "DISCORD_WEBHOOK_URL not set"
+
+**Cause:** Environment variable not loaded or `.env` file missing
+
+**Solutions:**
+
+1. Verify `.env` file exists in project root
+2. Check `.env` contains `DISCORD_WEBHOOK_URL=...` line
+3. Ensure no extra spaces around `=` sign
+4. Verify `.env` file has read permissions
+
+```bash
+# Check if .env exists
+ls -la .env
+
+# Verify content
+cat .env | grep DISCORD_WEBHOOK_URL
+```
+
+### "Failed to send Discord notification"
+
+**Cause:** Network error, invalid webhook, or webhook deleted
+
+**Solutions:**
+
+1. **Verify webhook URL is active:**
+   - Open Discord → Server Settings → Integrations → Webhooks
+   - Confirm webhook still exists
+   - If deleted, create new webhook and update `.env`
+
+2. **Test webhook directly:**
+
+   ```bash
+   curl -X POST "YOUR_WEBHOOK_URL" \
+     -H "Content-Type: application/json" \
+     -d '{"content": "Test message"}'
+   ```
+
+3. **Check network connectivity:**
+
+   ```bash
+   ping discord.com
+   ```
+
+4. **Verify webhook permissions:**
+   - Webhook must have permission to post in target channel
+   - Check channel permissions in Discord
+
+### Messages Not Appearing
+
+**Cause:** Channel visibility or webhook configuration issues
+
+**Solutions:**
+
+1. Verify you have access to the target channel
+2. Check channel is not muted or hidden
+3. Confirm webhook is assigned to correct channel
+4. Try sending to different channel
+
+### Special Characters Breaking Messages
+
+**Cause:** Unescaped quotes or shell special characters
+
+**Solutions:**
+
+**Use single quotes for outer string:**
+
+```bash
+./.claude/hooks/send-discord.sh 'Message with "double quotes" works fine'
+```
+
+**Escape single quotes inside single-quoted strings:**
+
+```bash
+./.claude/hooks/send-discord.sh 'User'\''s profile updated'
+```
+
+**Use double quotes and escape:**
+
+```bash
+./.claude/hooks/send-discord.sh "Message with \"escaped quotes\""
+```
+
+**For complex messages, use heredoc:**
+
+```bash
+./.claude/hooks/send-discord.sh "$(cat <<'EOF'
+Multi-line message
+With special characters: ' " $ `
+All work fine here
+EOF
+)"
+```
+
+### Script Permission Denied
+
+**Cause:** Script not executable
+
+**Solution:**
+
+```bash
+chmod +x ./.claude/hooks/send-discord.sh
+```
+
+## Advanced Configuration
+
+### Multiple Discord Channels
+
+Send different notification types to different channels:
+
+**.env file:**
+
+```bash
+DISCORD_WEBHOOK_SUCCESS=https://discord.com/api/webhooks/.../success-channel
+DISCORD_WEBHOOK_ERROR=https://discord.com/api/webhooks/.../error-channel
+DISCORD_WEBHOOK_INFO=https://discord.com/api/webhooks/.../info-channel
+```
+
+**Create wrapper scripts:**
+
+```bash
+# send-discord-success.sh
+export DISCORD_WEBHOOK_URL="$DISCORD_WEBHOOK_SUCCESS"
+./.claude/hooks/send-discord.sh "$1"
+
+# send-discord-error.sh
+export DISCORD_WEBHOOK_URL="$DISCORD_WEBHOOK_ERROR"
+./.claude/hooks/send-discord.sh "$1"
+```
+
+### Custom Embed Colors
+
+Edit `send-discord.sh` to change embed color:
+
+```bash
+# Line 33: "color": 5763719
+# Change to:
+"color": 15158332  # Red
+"color": 3066993   # Green
+"color": 15844367  # Yellow
+"color": 3447003   # Blue
+```
+
+### Adding Custom Fields
+
+Edit `send-discord.sh` to add more fields:
+
+```bash
+# After line 48, add:
+{
+    "name": "🔧 Environment",
+    "value": "Production",
+    "inline": true
+},
+{
+    "name": "🌿 Branch",
+    "value": "$(git branch --show-current)",
+    "inline": true
+}
+```
+
+### Conditional Notifications
+
+Only send notifications for specific conditions:
+
+```bash
+#!/bin/bash
+# deploy.sh
+
+if npm run test; then
+    if [[ "$ENVIRONMENT" == "production" ]]; then
+        ./.claude/hooks/send-discord.sh '✅ Production deployment successful'
+    fi
+else
+    # Always notify on failures
+    ./.claude/hooks/send-discord.sh '❌ Tests failed - deployment aborted'
+fi
+```
+
+## Security Best Practices
+
+1. **Never commit webhook URLs:**
+
+   ```bash
+   # .gitignore
+   .env
+   .env.*
+   .env.local
+   ```
+
+2. **Use environment variables:** Never hardcode webhooks in scripts
+
+3. **Rotate webhooks regularly:**
+   - Delete old webhook in Discord
+   - Create new webhook
+   - Update `.env` file
+
+4. **Limit webhook permissions:**
+   - Only grant webhook access to necessary channels
+   - Use read-only channels for notifications
+
+5. **Monitor webhook usage:**
+   - Check Discord audit log regularly
+   - Look for unexpected webhook activity
+
+6. **Use separate webhooks per environment:**
+
+   ```bash
+   # .env.development
+   DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/.../dev-channel
+
+   # .env.production
+   DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/.../prod-channel
+   ```
+
+## Reference
+
+**Script Location:** `.claude/hooks/send-discord.sh`
+
+**Configuration File:** `.env` (project root)
+
+**Required Environment Variable:** `DISCORD_WEBHOOK_URL`
+
+**Supported Shell:** Bash
+
+**Dependencies:**
+
+- `curl` (pre-installed on macOS/Linux)
+- `jq` (optional, for testing)
+
+**Discord API Documentation:** https://discord.com/developers/docs/resources/webhook
+
+**Claude Code Documentation:** https://docs.claude.com/claude-code
+
+---
+
+**Last Updated:** 2025-10-22

package/.claude/hooks/discord_notify.sh

@@ -0,0 +1,221 @@
+#!/bin/bash
+
+# Discord Notification Hook for Claude Code
+# This hook sends a notification to Discord when Claude finishes a task
+
+set -euo pipefail
+
+# Load environment variables with priority: process.env > .claude/.env > .claude/hooks/.env
+load_env() {
+    # 1. Start with lowest priority: .claude/hooks/.env
+    if [[ -f "$(dirname "$0")/.env" ]]; then
+        set -a
+        source "$(dirname "$0")/.env"
+        set +a
+    fi
+
+    # 2. Override with .claude/.env
+    if [[ -f .claude/.env ]]; then
+        set -a
+        source .claude/.env
+        set +a
+    fi
+
+    # 3. Process env (already loaded) has highest priority - no action needed
+    # Variables already in process.env will not be overwritten by 'source'
+}
+
+load_env
+
+# Read JSON input from stdin
+INPUT=$(cat)
+
+# Extract relevant information from the hook input
+HOOK_TYPE=$(echo "$INPUT" | jq -r '.hookType // "unknown"')
+PROJECT_DIR=$(echo "$INPUT" | jq -r '.projectDir // ""')
+TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+SESSION_ID=$(echo "$INPUT" | jq -r '.sessionId // ""')
+PROJECT_NAME=$(basename "$PROJECT_DIR")
+
+# Configuration - these will be set via environment variables
+DISCORD_WEBHOOK_URL="${DISCORD_WEBHOOK_URL:-}"
+
+# Validate required environment variables
+if [[ -z "$DISCORD_WEBHOOK_URL" ]]; then
+    echo "⚠️  Discord notification skipped: DISCORD_WEBHOOK_URL not set" >&2
+    exit 0
+fi
+
+# Function to send Discord message with embeds
+send_discord_embed() {
+    local title="$1"
+    local description="$2"
+    local color="$3"
+    local fields="$4"
+
+    local payload=$(cat <<EOF
+{
+    "embeds": [{
+        "title": "$title",
+        "description": "$description",
+        "color": $color,
+        "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%S.000Z)",
+        "footer": {
+            "text": "DevPocket API • ${PROJECT_NAME}"
+        },
+        "fields": $fields
+    }]
+}
+EOF
+)
+
+    curl -s -X POST "$DISCORD_WEBHOOK_URL" \
+        -H "Content-Type: application/json" \
+        -d "$payload" > /dev/null 2>&1
+}
+
+# Generate summary based on hook type
+case "$HOOK_TYPE" in
+    "Stop")
+        # Extract tool usage summary
+        TOOLS_USED=$(echo "$INPUT" | jq -r '.toolsUsed[]?.tool // empty' | sort | uniq -c | sort -nr)
+        FILES_MODIFIED=$(echo "$INPUT" | jq -r '.toolsUsed[]? | select(.tool == "Edit" or .tool == "Write" or .tool == "MultiEdit") | .parameters.file_path // empty' | sort | uniq)
+
+        # Count operations
+        TOTAL_TOOLS=$(echo "$INPUT" | jq '.toolsUsed | length')
+
+        # Build description
+        DESCRIPTION="✅ Claude Code session completed successfully"
+
+        # Build tools used text
+        TOOLS_TEXT=""
+        if [[ -n "$TOOLS_USED" ]]; then
+            TOOLS_TEXT=$(echo "$TOOLS_USED" | while read count tool; do
+                echo "• **${count}** ${tool}"
+            done | paste -sd '\n' -)
+        else
+            TOOLS_TEXT="No tools used"
+        fi
+
+        # Build files modified text
+        FILES_TEXT=""
+        if [[ -n "$FILES_MODIFIED" ]]; then
+            FILES_TEXT=$(echo "$FILES_MODIFIED" | while IFS= read -r file; do
+                if [[ -n "$file" ]]; then
+                    relative_file=$(echo "$file" | sed "s|^${PROJECT_DIR}/||")
+                    echo "• \`${relative_file}\`"
+                fi
+            done | paste -sd '\n' -)
+        else
+            FILES_TEXT="No files modified"
+        fi
+
+        # Build fields JSON
+        FIELDS=$(cat <<EOF
+[
+    {
+        "name": "⏰ Session Time",
+        "value": "${TIMESTAMP}",
+        "inline": true
+    },
+    {
+        "name": "🔧 Total Operations",
+        "value": "${TOTAL_TOOLS}",
+        "inline": true
+    },
+    {
+        "name": "🆔 Session ID",
+        "value": "\`${SESSION_ID:0:8}...\`",
+        "inline": true
+    },
+    {
+        "name": "📦 Tools Used",
+        "value": "${TOOLS_TEXT}",
+        "inline": false
+    },
+    {
+        "name": "📝 Files Modified",
+        "value": "${FILES_TEXT}",
+        "inline": false
+    },
+    {
+        "name": "📍 Location",
+        "value": "\`${PROJECT_DIR}\`",
+        "inline": false
+    }
+]
+EOF
+)
+
+        send_discord_embed "🤖 Claude Code Session Complete" "$DESCRIPTION" 5763719 "$FIELDS"
+        ;;
+
+    "SubagentStop")
+        SUBAGENT_TYPE=$(echo "$INPUT" | jq -r '.subagentType // "unknown"')
+
+        DESCRIPTION="Specialized agent completed its task"
+
+        FIELDS=$(cat <<EOF
+[
+    {
+        "name": "⏰ Time",
+        "value": "${TIMESTAMP}",
+        "inline": true
+    },
+    {
+        "name": "🔧 Agent Type",
+        "value": "${SUBAGENT_TYPE}",
+        "inline": true
+    },
+    {
+        "name": "🆔 Session ID",
+        "value": "\`${SESSION_ID:0:8}...\`",
+        "inline": true
+    },
+    {
+        "name": "📍 Location",
+        "value": "\`${PROJECT_DIR}\`",
+        "inline": false
+    }
+]
+EOF
+)
+
+        send_discord_embed "🎯 Claude Code Subagent Complete" "$DESCRIPTION" 3447003 "$FIELDS"
+        ;;
+
+    *)
+        DESCRIPTION="Claude Code event triggered"
+
+        FIELDS=$(cat <<EOF
+[
+    {
+        "name": "⏰ Time",
+        "value": "${TIMESTAMP}",
+        "inline": true
+    },
+    {
+        "name": "📋 Event Type",
+        "value": "${HOOK_TYPE}",
+        "inline": true
+    },
+    {
+        "name": "🆔 Session ID",
+        "value": "\`${SESSION_ID:0:8}...\`",
+        "inline": true
+    },
+    {
+        "name": "📍 Location",
+        "value": "\`${PROJECT_DIR}\`",
+        "inline": false
+    }
+]
+EOF
+)
+
+        send_discord_embed "📝 Claude Code Event" "$DESCRIPTION" 10070709 "$FIELDS"
+        ;;
+esac
+
+# Log the notification (optional)
+echo "✅ Discord notification sent for $HOOK_TYPE event in project $PROJECT_NAME" >&2