Multi-Agent Observability System

Real-time monitoring and visualization for Claude Code agents through comprehensive hook event tracking. You can watch the full breakdown here and watch the latest enhancement where we compare Haiku 4.5 and Sonnet 4.5 here.

🎯 Overview

This system provides complete observability into Claude Code agent behavior by capturing, storing, and visualizing Claude Code Hook events in real-time. It enables monitoring of multiple concurrent agents with session tracking, event filtering, and live updates.

🏗️ Architecture

Claude Agents → Hook Scripts → HTTP POST → Bun Server → SQLite → WebSocket → Vue Client

📋 Setup Requirements

Before getting started, ensure you have the following installed:

Claude Code - Anthropic's official CLI for Claude
Astral uv - Fast Python package manager (required for hook scripts)
Bun, npm, or yarn - For running the server and client
Anthropic API Key - Set as ANTHROPIC_API_KEY environment variable
OpenAI API Key (optional) - For multi-model support with just-prompt MCP tool
ElevenLabs API Key (optional) - For audio features

Configure .claude Directory

To setup observability in your repo,we need to copy the .claude directory to your project root.

To integrate the observability hooks into your projects:

Copy the entire .claude directory to your project root:
```
cp -R .claude /path/to/your/project/
```

Update the settings.json configuration:

Open .claude/settings.json in your project and modify the source-app parameter to identify your project:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "uv run .claude/hooks/pre_tool_use.py"
        },
        {
          "type": "command",
          "command": "uv run .claude/hooks/send_event.py --source-app YOUR_PROJECT_NAME --event-type PreToolUse --summarize"
        }
      ]
    }],
    "PostToolUse": [{
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "uv run .claude/hooks/post_tool_use.py"
        },
        {
          "type": "command",
          "command": "uv run .claude/hooks/send_event.py --source-app YOUR_PROJECT_NAME --event-type PostToolUse --summarize"
        }
      ]
    }],
    "UserPromptSubmit": [{
      "hooks": [
        {
          "type": "command",
          "command": "uv run .claude/hooks/user_prompt_submit.py --log-only"
        },
        {
          "type": "command",
          "command": "uv run .claude/hooks/send_event.py --source-app YOUR_PROJECT_NAME --event-type UserPromptSubmit --summarize"
        }
      ]
    }]
    // ... (similar patterns for Notification, Stop, SubagentStop, PreCompact, SessionStart, SessionEnd)
  }
}

Replace YOUR_PROJECT_NAME with a unique identifier for your project (e.g., my-api-server, react-app, etc.).

Ensure the observability server is running:

# From the observability project directory (this codebase)
./scripts/start-system.sh

Now your project will send events to the observability system whenever Claude Code performs actions.

🚀 Quick Start

You can quickly view how this works by running this repositories .claude setup.

# 1. Start both server and client
./scripts/start-system.sh

# 2. Open http://localhost:5173 in your browser

# 3. Open Claude Code and run the following command:
Run git ls-files to understand the codebase.

# 4. Watch events stream in the client

# 5. Copy the .claude folder to other projects you want to emit events from.
cp -R .claude <directory of your codebase you want to emit events from>

📁 Project Structure

claude-code-hooks-multi-agent-observability/
│
├── apps/                    # Application components
│   ├── server/             # Bun TypeScript server
│   │   ├── src/
│   │   │   ├── index.ts    # Main server with HTTP/WebSocket endpoints
│   │   │   ├── db.ts       # SQLite database management & migrations
│   │   │   └── types.ts    # TypeScript interfaces
│   │   ├── package.json
│   │   └── events.db       # SQLite database (gitignored)
│   │
│   └── client/             # Vue 3 TypeScript client
│       ├── src/
│       │   ├── App.vue     # Main app with theme & WebSocket management
│       │   ├── components/
│       │   │   ├── EventTimeline.vue      # Event list with auto-scroll
│       │   │   ├── EventRow.vue           # Individual event display
│       │   │   ├── FilterPanel.vue        # Multi-select filters
│       │   │   ├── ChatTranscriptModal.vue # Chat history viewer
│       │   │   ├── StickScrollButton.vue  # Scroll control
│       │   │   └── LivePulseChart.vue     # Real-time activity chart
│       │   ├── composables/
│       │   │   ├── useWebSocket.ts        # WebSocket connection logic
│       │   │   ├── useEventColors.ts      # Color assignment system
│       │   │   ├── useChartData.ts        # Chart data aggregation
│       │   │   └── useEventEmojis.ts      # Event type emoji mapping
│       │   ├── utils/
│       │   │   └── chartRenderer.ts       # Canvas chart rendering
│       │   └── types.ts    # TypeScript interfaces
│       ├── .env.sample     # Environment configuration template
│       └── package.json
│
├── .claude/                # Claude Code integration
│   ├── hooks/             # Hook scripts (Python with uv)
│   │   ├── send_event.py  # Universal event sender
│   │   ├── pre_tool_use.py    # Tool validation & blocking
│   │   ├── post_tool_use.py   # Result logging
│   │   ├── notification.py    # User interaction events
│   │   ├── user_prompt_submit.py # User prompt logging & validation
│   │   ├── stop.py           # Session completion
│   │   └── subagent_stop.py  # Subagent completion
│   │
│   └── settings.json      # Hook configuration
│
├── scripts/               # Utility scripts
│   ├── start-system.sh   # Launch server & client
│   ├── reset-system.sh   # Stop all processes
│   └── test-system.sh    # System validation
│
└── logs/                 # Application logs (gitignored)

🔧 Component Details

1. Hook System (`.claude/hooks/`)

If you want to master claude code hooks watch this video

The hook system intercepts Claude Code lifecycle events:

send_event.py: Core script that sends event data to the observability server
- Supports --add-chat flag for including conversation history
- Validates server connectivity before sending
- Handles all event types with proper error handling
Event-specific hooks: Each implements validation and data extraction
- pre_tool_use.py: Blocks dangerous commands, validates tool usage
- post_tool_use.py: Captures execution results and outputs
- notification.py: Tracks user interaction points
- user_prompt_submit.py: Logs user prompts, supports validation (v1.0.54+)
- stop.py: Records session completion with optional chat history
- subagent_stop.py: Monitors subagent task completion
- pre_compact.py: Tracks context compaction operations (manual/auto)
- session_start.py: Logs session start, can load development context
- session_end.py: Logs session end, saves session statistics

2. Server (`apps/server/`)

Bun-powered TypeScript server with real-time capabilities:

Database: SQLite with WAL mode for concurrent access
Endpoints:
- POST /events - Receive events from agents
- GET /events/recent - Paginated event retrieval with filtering
- GET /events/filter-options - Available filter values
- WS /stream - Real-time event broadcasting
Features:
- Automatic schema migrations
- Event validation
- WebSocket broadcast to all clients
- Chat transcript storage

3. Client (`apps/client/`)

Vue 3 application with real-time visualization:

Visual Design:
- Dual-color system: App colors (left border) + Session colors (second border)
- Gradient indicators for visual distinction
- Dark/light theme support
- Responsive layout with smooth animations
Features:
- Real-time WebSocket updates
- Multi-criteria filtering (app, session, event type)
- Live pulse chart with session-colored bars and event type indicators
- Time range selection (1m, 3m, 5m) with appropriate data aggregation
- Chat transcript viewer with syntax highlighting
- Auto-scroll with manual override
- Event limiting (configurable via VITE_MAX_EVENTS_TO_DISPLAY)
Live Pulse Chart:
- Canvas-based real-time visualization
- Session-specific colors for each bar
- Event type emojis displayed on bars
- Smooth animations and glow effects
- Responsive to filter changes

🔄 Data Flow

Event Generation: Claude Code executes an action (tool use, notification, etc.)
Hook Activation: Corresponding hook script runs based on settings.json configuration
Data Collection: Hook script gathers context (tool name, inputs, outputs, session ID)
Transmission: send_event.py sends JSON payload to server via HTTP POST
Server Processing:
- Validates event structure
- Stores in SQLite with timestamp
- Broadcasts to WebSocket clients
Client Update: Vue app receives event and updates timeline in real-time

🎨 Event Types & Visualization

Event Type	Emoji	Purpose	Color Coding	Special Display
PreToolUse	🔧	Before tool execution	Session-based	Tool name & details
PostToolUse	✅	After tool completion	Session-based	Tool name & results
Notification	🔔	User interactions	Session-based	Notification message
Stop	🛑	Response completion	Session-based	Summary & chat transcript
SubagentStop	👥	Subagent finished	Session-based	Subagent details
PreCompact	📦	Context compaction	Session-based	Compaction details
UserPromptSubmit	💬	User prompt submission	Session-based	Prompt: "user message" (italic)
SessionStart	🚀	Session started	Session-based	Session source (startup/resume/clear)
SessionEnd	🏁	Session ended	Session-based	End reason (clear/logout/exit/other)

UserPromptSubmit Event (v1.0.54+)

The UserPromptSubmit hook captures every user prompt before Claude processes it. In the UI:

Displays as Prompt: "user's message" in italic text
Shows the actual prompt content inline (truncated to 100 chars)
Summary appears on the right side when AI summarization is enabled
Useful for tracking user intentions and conversation flow

🔌 Integration

For New Projects

Copy the event sender:

cp .claude/hooks/send_event.py YOUR_PROJECT/.claude/hooks/

Add to your .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "uv run .claude/hooks/send_event.py --source-app YOUR_APP --event-type PreToolUse"
      }]
    }]
  }
}

For This Project

Already integrated! Hooks run both validation and observability:

{
  "type": "command",
  "command": "uv run .claude/hooks/pre_tool_use.py"
},
{
  "type": "command", 
  "command": "uv run .claude/hooks/send_event.py --source-app cc-hooks-observability --event-type PreToolUse"
}

🧪 Testing

# System validation
./scripts/test-system.sh

# Manual event test
curl -X POST http://localhost:4000/events \
  -H "Content-Type: application/json" \
  -d '{
    "source_app": "test",
    "session_id": "test-123",
    "hook_event_type": "PreToolUse",
    "payload": {"tool_name": "Bash", "tool_input": {"command": "ls"}}
  }'

⚙️ Configuration

Environment Variables

Copy .env.sample to .env in the project root and fill in your API keys:

Application Root (.env file):

ANTHROPIC_API_KEY – Anthropic Claude API key (required)
ENGINEER_NAME – Your name (for logging/identification)
GEMINI_API_KEY – Google Gemini API key (optional)
OPENAI_API_KEY – OpenAI API key (optional)
ELEVEN_API_KEY – ElevenLabs API key (optional)

Client (.env file in apps/client/.env):

VITE_MAX_EVENTS_TO_DISPLAY=100 – Maximum events to show (removes oldest when exceeded)

Server Ports

Server: 4000 (HTTP/WebSocket)
Client: 5173 (Vite dev server)

🛡️ Security Features

Blocks dangerous commands (rm -rf, etc.)
Prevents access to sensitive files (.env, private keys)
Validates all inputs before execution
No external dependencies for core functionality

📊 Technical Stack

Server: Bun, TypeScript, SQLite
Client: Vue 3, TypeScript, Vite, Tailwind CSS
Hooks: Python 3.8+, Astral uv, TTS (ElevenLabs or OpenAI), LLMs (Claude or OpenAI)
Communication: HTTP REST, WebSocket

🔧 Troubleshooting

Hook Scripts Not Working

If your hook scripts aren't executing properly, it might be due to relative paths in your .claude/settings.json. Claude Code documentation recommends using absolute paths for command scripts.

Solution: Use the custom Claude Code slash command to automatically convert all relative paths to absolute paths:

# In Claude Code, simply run:
/convert_paths_absolute

This command will:

Find all relative paths in your hook command scripts
Convert them to absolute paths based on your current working directory
Create a backup of your original settings.json
Show you exactly what changes were made

This ensures your hooks work correctly regardless of where Claude Code is executed from.

Master AI Agentic Coding

And prepare for the future of software engineering

Learn tactical agentic coding patterns with Tactical Agentic Coding

Follow the IndyDevDan YouTube channel to improve your agentic coding advantage.

disler/claude-code-hooks-multi-agent-observability