claude-code-monitor/.claude/hooks

Claude Code Monitor Hooks

These hooks capture Claude Code events and send them to the monitoring backend.

Installation

Local Installation (localhost)

# Copy hooks to Claude Code directory
cp .claude/hooks/*.sh ~/.claude/hooks/

# Make hooks executable
chmod +x ~/.claude/hooks/*.sh

The hooks will automatically use http://localhost:8000 as the backend URL.

Remote/VM Installation

Method 1: Config File (Recommended)

Create a config file with your backend URL:

# Set backend URL in config file
echo "http://your-vm-ip:8000" > ~/.claude/monitor_url

# Or for specific domain
echo "http://monitor.example.com:8000" > ~/.claude/monitor_url

# Copy and enable hooks
cp .claude/hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

Method 2: Environment Variable

For remote installations, set the CLAUDE_MONITOR_URL environment variable:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export CLAUDE_MONITOR_URL="http://your-vm-ip:8000"

# IMPORTANT: Restart terminal or run
source ~/.bashrc

# Then copy and enable hooks
cp .claude/hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

Priority Order:

1. Config file (~/.claude/monitor_url) - highest priority
2. Environment variable (CLAUDE_MONITOR_URL)
3. Default (http://localhost:8000)

Docker Deployment Examples

# Backend on port 8000
echo "http://192.168.1.100:8000" > ~/.claude/monitor_url

# Backend via nginx on port 3000
echo "http://192.168.1.100:3000" > ~/.claude/monitor_url

# With domain
echo "http://monitor.example.com:8000" > ~/.claude/monitor_url

Verification

Test if hooks are working:

# Check if environment variable is set
echo $CLAUDE_MONITOR_URL

# Manually test a hook
echo '{"session_id":"test","timestamp":1234567890}' | ~/.claude/hooks/session_start.sh

# Check backend logs for the test event
curl http://your-backend:8000/api/events | jq

Available Hooks

• pre_tool_use.sh - Before tool execution
• post_tool_use.sh - After tool execution
• user_prompt.sh - When user submits a prompt
• session_start.sh - Session initialization
• session_end.sh - Session termination
• subagent_stop.sh - Agent completion

Troubleshooting

No events appearing in dashboard

1. Check if CLAUDE_MONITOR_URL is set correctly:

   echo $CLAUDE_MONITOR_URL
   

2. Verify backend is reachable:

   curl $CLAUDE_MONITOR_URL/health
   

3. Check hook permissions:

   ls -la ~/.claude/hooks/*.sh
   

4. Test hook manually:

   echo '{"session_id":"test","timestamp":1234567890}' | ~/.claude/hooks/session_start.sh
   

Events only work locally

Make sure to set CLAUDE_MONITOR_URL in your shell profile and restart your terminal.