MadameClaude

Madame Claude - Claude Code Hook Monitor

Madame Claude is a real-time monitoring system for Claude Code hooks that captures and streams tool usage events to a web interface. It provides visibility into Claude Code's tool usage patterns, helping developers understand and debug their AI assistant's behavior.

Overview

Madame Claude consists of three components that work together to capture, process, and display Claude Code hook events:

1. bridge - Captures hook events from stdin and forwards them via HTTP
2. server - Receives events and broadcasts them to connected web clients
3. monitor - Web interface for real-time event visualization with sound notifications

Architecture

Data Flow

Features

- Real-time Monitoring: See Claude Code events as they happen
- Event Filtering: Filter by session, tool, or event type
- Sound Notifications: Customizable sounds for Notification and Stop events
- Color-coded Console: Server logs with colored event types and tool names
- Persistent Settings: Volume controls saved to browser localStorage
- Multiple Event Types: Supports all Claude Code hook types:
  - PreToolUse
  - PostToolUse
  - Notification
  - Stop
  - SubagentStop

Installation

Prerequisites

- Node.js installed on your system
- Claude Code installed and configured

Setup

1. Clone the repository:

2. Install and start the server:

The server will start on http://localhost:4519

3. Configure Claude Code hooks in ~/.claude/settings.json (macOS/Linux) or %USERPROFILE%\.claude\settings.json (Windows):

Note: Replace /path/to/MadameClaude with the actual path to your Madame Claude installation.

4. Open the web monitor:
   - Navigate to http://localhost:4519 in your browser
   - The monitor will automatically connect to the server via WebSocket

Usage

Web Monitor…