Skip to main content

logsession-monitor

logsession-monitor is a unified CLI for real-time monitoring of Claude Code sessions. It provides both a web-based dashboard and terminal-based monitoring modes.

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 (automatically opens browser)
logsession-monitor

# The web UI opens at https://session-monitor.microwiseai.com
# WebSocket server runs locally on port 41820

CLI Commands​

Basic Usage​

CommandDescription
logsession-monitorStart monitor and open browser (default mode)
logsession-monitor --serveStart server only (no browser)
logsession-monitor managerStart with Manager-Worker hierarchy UI
logsession-monitor --helpShow help
logsession-monitor --versionShow version

Monitoring Modes​

ModeCommandDescription
Defaultlogsession-monitorOpens web UI in browser
Serverlogsession-monitor --serveRuns server without opening browser
Watchlogsession-monitor --watchTerminal htop-like fixed display
Streamlogsession-monitor --streamTerminal scrolling log output
Notifylogsession-monitor --notifySend status changes via messenger

CLI Options​

logsession-monitor [subcommand] [options]

Subcommands:
  (none)      Default monitor UI (flat session list)
  manager     Manager-Worker hierarchy UI

Options:
  -s, --serve           Start web server only (no browser)
  -w, --watch           Watch mode: htop-like fixed display
  --stream              Stream mode: scrolling log output
  --notify              Notify mode: send status changes via messenger
  -f, --filter <prefix> Filter sessions by prefix
  -p, --port <port>     Server port (default: 41820)
  -v, --verbose <level> Verbose level: 0-3 (default: 1)
  -l, --lines <num>     Detection lines (default: 200)
  --source <type>       Data source: file, websocket (default: file)
  -u, --url <url>       WebSocket URL for remote mode
  -h, --help            Show help
  -V, --version         Show version

Stream/Watch Dynamic Filter Options:
  --add <session>       Add exact session to filter
  --add --filter <pat>  Add pattern to filter (prefix match)
  --remove <session>    Remove exact session from filter
  --remove --filter <p> Remove pattern from filter
  --include-self        Include own session (default: excluded)

Usage Examples​

Web UI Mode (Default)​

# Start monitor - opens browser automatically
logsession-monitor

# Start on custom port
logsession-monitor --port 3458

# Start Manager UI mode
logsession-monitor manager

# Start Manager UI on custom port
logsession-monitor manager --serve --port 3458

Terminal Watch Mode​

The watch mode provides an htop-like fixed display in your terminal:

# Watch all sessions
logsession-monitor --watch

# Watch with session filter
logsession-monitor --watch --filter "worker-"

# Watch on different port
logsession-monitor --watch --port 3457

# Press 'q' to quit

Terminal Stream Mode​

Stream mode provides scrolling log output:

# Stream all session updates
logsession-monitor --stream

# Stream with filter
logsession-monitor --stream --filter "my-project"

Notify Mode​

Receive session status changes as messenger notifications to your current session:

# Notify for a specific session
logsession-monitor --notify --add my-session

# Notify for sessions matching a pattern
logsession-monitor --notify --filter "worker-"

# Notify for multiple sessions
logsession-monitor --notify --add worker-1 --add worker-2

This is useful for managers who want to be notified when worker sessions change status (e.g., when a worker finishes a task and becomes idle).

Dynamic Filter Options (Stream/Watch/Notify Mode)​

Add or remove sessions from the filter dynamically:

# Add exact session to filter
logsession-monitor --stream --add worker-1

# Add pattern to filter (prefix match)
logsession-monitor --stream --add --filter "worker-"

# Remove exact session from filter
logsession-monitor --stream --remove worker-1

# Remove pattern from filter
logsession-monitor --stream --remove --filter "worker-"

# Include own session (default: excluded)
logsession-monitor --stream --include-self

Remote Mode​

Connect to a remote WebSocket server:

logsession-monitor --source websocket --url ws://example.com:41820

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

Architecture​

+-------------------------------------------+
|   logsession-monitor                       |
+-------------------------------------------+
|   Mode: default or manager                |
|   HTTP:      http://localhost:41820       |
|   WebSocket: ws://localhost:41820         |
+-------------------------------------------+
         |
         v
+-------------------------------------------+
|   Cloudflare Pages (Web UI)               |
|   https://session-monitor.microwiseai.com |
|   Connects back to local WebSocket        |
+-------------------------------------------+

In default mode, the CLI:

  1. Starts a local WebSocket server on port 41820
  2. Opens the hosted web UI at session-monitor.microwiseai.com
  3. The web UI connects back to your local WebSocket server

Web Interface​

Key Features​

  • Real-time Dashboard: View all sessions at a glance
  • Status Display: Color-coded current status for each session
  • Unchanged Time: Shows how long each session has been in current state
  • WebSocket Connection: Real-time updates (no page refresh needed)
  • Session Add/Remove: Manage sessions directly from the UI
  • Google Login: Sign in with Google for personalized settings
  • PWA Support: Install as a desktop app for quick access

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:

# 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

Example Response​

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

WebSocket API​

Connect to the WebSocket server for real-time updates:

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

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

  switch (data.type) {
    case 'init':
      // Initial session list
      console.log(data.sessions)
      break
    case 'claude_status_updated':
      // Session status update
      console.log(data.session)
      break
    case 'session_created':
      console.log('New session:', data.session)
      break
    case 'session_deleted':
      console.log('Removed:', data.name)
      break
  }
}

Configuration​

Port Configuration​

# Via CLI option
logsession-monitor --port 8080

# Via environment variable
PORT=8080 logsession-monitor

Verbose Levels​

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

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

# Verbose mode
logsession-monitor --verbose 2

# Debug mode
logsession-monitor --verbose 3

Troubleshooting​

Browser Doesn't Open​

If the browser doesn't open automatically, navigate manually to:

  • Web UI: https://session-monitor.microwiseai.com
  • Make sure your local WebSocket server is running on port 41820

Session Not Detected​

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

Watch/Stream Mode Connection Failed​

Watch and stream modes require a running server:

# Terminal 1: Start server
logsession-monitor --serve

# Terminal 2: Connect with watch mode
logsession-monitor --watch

Version Info​

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