Claude Code Monitor

Real-time monitoring dashboard for Claude Code activity. Track tool usage, agent spawns, sessions, and events with a beautiful dark-themed web interface.

Features

• Real-time Event Tracking: Monitor Claude Code events as they happen via WebSocket
• Statistics Dashboard: Track total events, tools used, agents spawned, and sessions
• Event Filtering: Filter events by category (ALL, TOOLS, AGENTS, PROMPTS, SESSIONS)
• Dark Theme UI: Beautiful dark-themed interface optimized for developers
• Docker Deployment: Easy deployment with Docker Compose
• Non-intrusive Monitoring: Lightweight hooks that don't slow down Claude Code

Architecture

Claude Code → Hook Scripts → FastAPI Backend → WebSocket → React Frontend
                                  ↓
                              SQLite DB

Prerequisites

• Docker & Docker Compose (recommended)
• jq (for hook scripts): brew install jq (macOS) or apt-get install jq (Linux)
• Claude Code installed and configured

Quick Start

1. Clone or Download

cd /path/to/claude-monitor

2. Install Hooks

The hook scripts capture Claude Code events and send them to the backend.

./install_hooks.sh

This will:

• Copy hook scripts to ~/.claude/hooks/
• Display the configuration you need to add to ~/.claude/settings.json

3. Configure Claude Code

Add the following to your ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "/Users/YOUR_USERNAME/.claude/hooks/pre_tool_use.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "/Users/YOUR_USERNAME/.claude/hooks/post_tool_use.sh"
      }]
    }],
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "/Users/YOUR_USERNAME/.claude/hooks/session_start.sh"
      }]
    }],
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "/Users/YOUR_USERNAME/.claude/hooks/session_end.sh"
      }]
    }],
    "SubagentStop": [{
      "hooks": [{
        "type": "command",
        "command": "/Users/YOUR_USERNAME/.claude/hooks/subagent_stop.sh"
      }]
    }],
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "/Users/YOUR_USERNAME/.claude/hooks/user_prompt.sh"
      }]
    }]
  }
}

Important: Replace /Users/YOUR_USERNAME with your actual home directory path.

4. Start the Application

docker-compose up --build

This will:

• Build and start the FastAPI backend (port 8000)
• Build and start the React frontend (port 3000)
• Create a persistent SQLite database in ./data/

5. Open the Dashboard

Navigate to http://localhost:3000

You should see:

• Connection status indicator (green = connected)
• Statistics cards showing 0 events initially
• Empty event feed

6. Test It

Open a new terminal and use Claude Code:

claude

Start a conversation or run commands. You'll see events appear in the dashboard in real-time!

Development Setup

Backend (FastAPI)

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run development server
python -m app.main

Backend runs on http://localhost:8000

API documentation: http://localhost:8000/docs

Frontend (React + Vite)

cd frontend

# Install dependencies
npm install

# Run development server
npm run dev

Frontend runs on http://localhost:5173

API Endpoints

Events

• POST /api/events - Create new event (called by hooks)
• GET /api/events - List events with filtering
  • Query params: skip, limit, event_type, session_id, tool_name
• DELETE /api/events/reset - Reset all statistics

Statistics

• GET /api/statistics - Get current statistics
• GET /api/statistics/tools - Get tool usage breakdown
• GET /api/statistics/sessions - Get session list

WebSocket

• WS /ws - WebSocket connection for real-time updates

Health

• GET /health - Health check

Event Types

The monitor captures these Claude Code events:

Event Type	Description	Filter
PreToolUse	Before tool execution	TOOLS
PostToolUse	After tool execution	TOOLS
SessionStart	Session started	SESSIONS
SessionEnd	Session ended	SESSIONS
SubagentStop	Agent completed	AGENTS
UserPromptSubmit	User submitted prompt	PROMPTS

Configuration

Environment Variables

Backend (docker-compose.yml):

• DATABASE_URL - SQLite database path
• CORS_ORIGINS - Allowed CORS origins

Frontend (frontend/.env):

• VITE_API_URL - Backend API URL (default: http://localhost:8000)
• VITE_WS_URL - WebSocket URL (default: ws://localhost:8000/ws)

Troubleshooting

Hooks Not Working

Problem: Events not appearing in dashboard

Solutions:

1. Check hook scripts are executable:

   chmod +x ~/.claude/hooks/*.sh
   

2. Verify jq is installed:

   which jq
   

3. Test hook manually:

   echo '{"session_id":"test","tool_name":"Bash"}' | ~/.claude/hooks/post_tool_use.sh
   

4. Check backend logs:

   docker-compose logs backend
   

Backend Connection Issues

Problem: "DISCONNECTED" status in dashboard

Solutions:

1. Verify backend is running:

   curl http://localhost:8000/health
   

2. Check Docker containers:

   docker-compose ps
   

3. Restart services:

   docker-compose restart
   

Port Conflicts

Problem: Ports 8000 or 3000 already in use

Solutions:

1. Find process using port:

   lsof -i :8000
   lsof -i :3000
   

2. Kill the process or change ports in docker-compose.yml:

   ports:
     - "8001:8000"  # Backend
     - "3001:80"    # Frontend
   

Database Issues

Problem: Database errors or corruption

Solutions:

1. Stop containers:

   docker-compose down
   

2. Remove database:

   rm data/claude_monitor.db*
   

3. Restart:

   docker-compose up -d
   

Project Structure

claude-monitor/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI application
│   │   ├── database.py          # SQLAlchemy models
│   │   ├── schemas.py           # Pydantic schemas
│   │   ├── crud.py              # Database operations
│   │   ├── websocket.py         # WebSocket manager
│   │   └── api/
│   │       ├── events.py        # Event endpoints
│   │       ├── statistics.py    # Statistics endpoints
│   │       └── websocket_endpoint.py
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── App.tsx              # Main component
│   │   ├── components/          # React components
│   │   ├── hooks/               # Custom hooks
│   │   ├── api/                 # API clients
│   │   ├── types/               # TypeScript types
│   │   └── styles/              # CSS styles
│   ├── package.json
│   ├── vite.config.ts
│   └── Dockerfile
├── .claude/
│   └── hooks/                   # Hook scripts
├── data/                        # SQLite database (created on first run)
├── docker-compose.yml
├── install_hooks.sh
└── README.md

Performance

The monitor is designed to be lightweight and non-intrusive:

• Hook execution: <10ms (runs in background)
• Backend processing: <50ms per event
• WebSocket latency: <100ms
• Database size: ~1KB per event

For high-volume usage, events auto-delete after 10,000 entries (configurable).

Security

• Hooks run with your user permissions
• Backend only accepts localhost connections by default
• No authentication required (localhost only)
• For production: Add authentication and restrict CORS origins

Contributing

Contributions welcome! Areas for improvement:

• Agents Graph visualization
• Event search functionality
• Export events to CSV/JSON
• Session timeline view
• Advanced filtering
• Performance metrics
• Authentication system

License

MIT License - feel free to use and modify

Credits

Built with:

• FastAPI - Backend framework
• React - Frontend framework
• Vite - Build tool
• SQLAlchemy - Database ORM

Inspired by Claude Code's powerful hook system.

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review Claude Code documentation: https://code.claude.com/docs
3. Open an issue in this repository

Changelog

v1.0.0 (2025-12-15)

• Initial release
• Real-time event monitoring
• Statistics dashboard
• Event filtering
• Docker deployment
• Dark theme UI