Skip to main content

Introduction

Claude Session Tools is a real-time monitoring and management system for Claude Code sessions. It provides visibility into the state of running Claude Code instances, enabling developers to track activity, detect issues, and receive audio notifications when attention is required.

Overview​

When running multiple Claude Code sessions simultaneously, it becomes difficult to track which sessions need attention. Claude Session Tools addresses this challenge by providing:

  • Real-time status monitoring through a web interface
  • Automatic detection of session states (active, idle, waiting, stuck)
  • Ambient sound notifications for sessions requiring user input
  • WebSocket-based live updates

Architecture​

The system consists of the following components:

┌─────────────────────────────────────────────────────────┐
│                    Web Interface                         │
│              (React + Mantine + Vite)                   │
└─────────────────────────────────────────────────────────┘
                          │
                          │ WebSocket
                          ▼
┌─────────────────────────────────────────────────────────┐
│                   Express Server                         │
│            (WebSocket + REST API + chokidar)            │
└─────────────────────────────────────────────────────────┘
                          │
                          │ File System Watching
                          ▼
┌─────────────────────────────────────────────────────────┐
│                 Claude Code Sessions                     │
│              (via loggable-session logs)                │
└─────────────────────────────────────────────────────────┘

Key Concepts​

Session States​

Claude Session Tools tracks sessions through a two-level status system:

Primary StatusDescription
idleSession is ready and waiting for user input
activeClaude is processing (thinking, using tools, responding)
waitingClaude is waiting for user response (permission, question)
stuckNo activity detected for 15+ seconds
deadSession no longer exists

Status Detection​

The system analyzes terminal output patterns to determine the current state. Detection is based on recognizing specific character sequences that Claude Code outputs during different operations.

Ambient Sound​

When sessions enter a waiting or idle state for a configurable duration, ambient sounds or music can be played to notify the user. This is particularly useful when managing multiple sessions across different workspaces.

Requirements​

  • Node.js 18 or later
  • loggable-session (for session logging)
  • A modern web browser with Web Audio API support

Next Steps​