Session Monitoring

Claude Session Tools provides real-time monitoring of Claude Code sessions through file system watching and WebSocket communication.

How Monitoring Works

File System Watching

The system uses chokidar to watch log files created by loggable-session. When changes are detected:

1. The LogWatcher reads the updated log content
2. Content is passed to the StatusDetector for analysis
3. Status changes are broadcast via WebSocket to connected clients

const watcher = new LogWatcher({
  sessionName: 'my-session',
  logDir: '/path/to/logs',
  onUpdate: (output) => {
    const status = statusDetector.detectStatus(output);
    broadcast(status);
  }
});

Efficient Polling

The system uses OS-native file system events rather than polling:

chokidar.watch(logPath, {
  usePolling: false,  // Use native events
  stabilityThreshold: 200  // 200ms debounce
});

This approach minimizes CPU usage while maintaining responsiveness.

Session Lifecycle

Creating a Session

Sessions are created through the web interface or REST API:

1. User provides a session name
2. Server locates the corresponding log directory
3. LogWatcher begins monitoring the session
4. Initial status is sent to connected clients

Active Monitoring

While monitoring:

• File changes trigger status detection
• Status updates are broadcast in real-time
• Health state is tracked (ALIVE, STUCK, DEAD)
• Unchanged count increments during inactivity

Session Removal

When a session is removed:

1. LogWatcher stops monitoring
2. Session state is cleared from memory
3. Ambient sound stops if playing for that session
4. Connected clients receive removal notification

Multiple Session Management

The system supports monitoring multiple sessions simultaneously:

┌─────────────────────────────────────────────┐
│              Web Interface                   │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐       │
│  │Session A│ │Session B│ │Session C│       │
│  │ ACTIVE  │ │ WAITING │ │  IDLE   │       │
│  └─────────┘ └─────────┘ └─────────┘       │
└─────────────────────────────────────────────┘

Each session:

• Has independent status tracking
• Maintains its own configuration
• Can trigger ambient sounds independently
• Reports its own health state

Session Card Display

Each session card shows:

Element	Description
Session Name	The tmux session identifier
Primary Status	Current state (idle, active, waiting, stuck, dead)
Detail	Specific activity (thinking, using_tools, permission, etc.)
Health Badge	Overall health indicator
Timestamp	Last status update time
Settings Button	Access to sound configuration
Delete Button	Remove session from monitoring

Health States

The health system tracks session stability:

State	Condition
ALIVE	Session is responsive and changing state
STUCK	No state change for 15+ seconds
DEAD	Session no longer exists (tmux session closed)
RECOVERED	Previously stuck session became active again

Best Practices

Session Naming

Use descriptive, unique names for sessions:

logsession start frontend-feature-auth
logsession start backend-api-refactor

Monitoring Load

While the system can handle many sessions, consider:

• Each session requires file system watching
• Status detection runs on every file change
• WebSocket broadcasts go to all connected clients

For large numbers of sessions, consider running multiple instances of the monitoring server.

Log File Size

Log files grow over time. The system reads only recent content for status detection, but consider:

• Periodic log rotation
• Using loggable-session's built-in log management
• Clearing old sessions from the monitor when no longer needed