Skip to main content

logsession-monitor

logsession-monitor is a web-based tool for real-time monitoring of Claude Code session status. It tracks multiple sessions simultaneously and detects status changes.

Installation​

# Install glpkg installer (one-time setup)
npm install -g @glpkg/installer

# Install logsession-monitor
gitlab-install @session-tools/logsession-monitor

Quick Start​

# Start the monitor server
logsession-monitor

# Access in browser
# http://localhost:5001

CLI Commands​

Server Management​

CommandDescription
logsession-monitorStart monitor server (default)
logsession-monitor startStart monitor server
logsession-monitor start --port <port>Start on specified port
logsession-monitor start --devStart in development mode

Session Management​

CommandDescription
logsession-monitor watch <session>Start watching a session
logsession-monitor unwatch <session>Stop watching a session
logsession-monitor listList all sessions (active + watched)
logsession-monitor status [session]Show status of watched sessions

Miscellaneous​

CommandDescription
logsession-monitor --help, -hShow help
logsession-monitor --version, -vShow version

Server Options​

logsession-monitor start [options]

Options:
  --dev              Run in development mode (requires tsx)
  --port <port>      Set server port (default: 5001)
  --verbose [level]  Status change log level
                       0 = quiet (no logs)
                       1 = normal (status changes only, default)
                       2 = verbose (status changes + reasons)
                       3 = debug (status + reasons + last segment)

Usage Examples​

Basic Usage​

# Start server
logsession-monitor

# Start on custom port
logsession-monitor start --port 8080

# Start watching a session
logsession-monitor watch my-project

# Check status of watched sessions
logsession-monitor status

# Check specific session status
logsession-monitor status my-project

Managing Sessions via CLI​

# List all sessions
logsession-monitor list

# Example output:
# === Active Sessions ===
#   [watching] my-project
#   another-project
#
# === Watched Sessions ===
#   my-project: idle (waiting for input)

# Add session to watch
logsession-monitor watch my-project

# Stop watching a session
logsession-monitor unwatch my-project

Session Status​

The monitor automatically detects session status:

StatusColorDescription
idleGreenSession is ready, waiting for user input
activeYellowClaude is processing (thinking, using tools, responding)
waitingCyanClaude is waiting for user response (permissions, questions)
stuckRedNo activity for 15+ seconds
deadGraySession no longer exists

Web Interface​

Access the web UI at http://localhost:5001:

Key Features​

  • Real-time Dashboard: View all watched sessions at a glance
  • Status Display: Color-coded current status for each session
  • WebSocket Connection: Real-time updates (no page refresh needed)
  • Session Add/Remove: Manage sessions directly from the UI

Ambient Sound​

Play notification sounds for certain statuses:

  • Notifications when session is in waiting or idle state
  • Useful when managing multiple sessions simultaneously
  • Requires enabling sound in browser settings

REST API​

The monitor server provides a REST API:

Session API​

# List watched sessions
GET /api/sessions

# List active loggable-sessions
GET /api/loggable-sessions

# Start watching a session
POST /api/sessions
Body: { "name": "session-name" }

# Stop watching a session
DELETE /api/sessions/:name

Status API​

# Get all session status
GET /api/sessions

# Example response:
[
  {
    "name": "my-project",
    "claudeStatus": {
      "primary": "idle",
      "detail": "waiting for input",
      "health": "healthy",
      "timestamp": "2025-01-07T10:30:00.000Z"
    }
  }
]

WebSocket API​

WebSocket connection for real-time status updates:

const ws = new WebSocket('ws://localhost:5001')

ws.onmessage = (event) => {
  const data = JSON.parse(event.data)

  switch (data.type) {
    case 'status':
      // Session status update
      console.log(data.session, data.status)
      break
    case 'sessions':
      // Full session list
      console.log(data.sessions)
      break
  }
}

Configuration​

Port Configuration​

# Set via environment variable
PORT=8080 logsession-monitor

# Or via CLI option
logsession-monitor start --port 8080

Log Level​

# Quiet mode (no logs)
logsession-monitor start --verbose 0

# Normal mode (default)
logsession-monitor start --verbose 1

# Verbose mode
logsession-monitor start --verbose 2

# Debug mode
logsession-monitor start --verbose 3

Troubleshooting​

Server Won't Start​

# Check for built files
ls -la dist-server/server.js

# Build first if missing
npm run build

# Or run in development mode
logsession-monitor start --dev

Session Not Detected​

  1. Verify the session is running with logsession
  2. Check log directory: ~/.loggable-session/logs/
  3. Verify the session name is correct

Version Info​

  • Current Version: 1.5.0
  • License: SSPL-1.0
  • Repository: GitLab