Skip to main content

Project Structure

Session Tools is a collection of packages for managing and monitoring Claude Code sessions. All packages are published to the GitLab NPM registry under the @session-tools namespace.

Package Overview​

┌─────────────────────────────────────────────────────────────────┐
│                      @session-tools                              │
├──────────────────────┬──────────────────────────────────────────┤
│  logsession          │  Core session logging CLI                │
│  logsession-monitor  │  Real-time monitoring web UI             │
│  session-messenger   │  Inter-session communication             │
│  log-parser          │  Parse logs into structured turns        │
│  docs                │  This documentation site                 │
└──────────────────────┴──────────────────────────────────────────┘

Packages​

logsession (Core)​

The foundation of Session Tools. Provides automatic logging for Claude Code sessions running in tmux.

# Start a logged session
logsession start my-project

# List active sessions
logsession list

# Show session output
logsession show my-project

Repository: session-tools.ver1.loggable-session

logsession-monitor​

Real-time web interface for monitoring multiple Claude Code sessions. Detects session states and provides ambient sound notifications.

# Start the monitor server
logsession-monitor

Features:

  • Real-time status updates via WebSocket
  • Session state detection (active, idle, waiting, stuck)
  • Ambient sound notifications
  • Multi-session dashboard

Repository: session-tools.ver1.logsession-monitor

session-messenger​

Send messages between Claude Code sessions. Useful for coordinating work across multiple sessions.

# Send a message to another session
messenger send target-session "Hello from here"

# Wait for a response
messenger wait --timeout 30

Repository: session-tools.ver1.session-messenger

log-parser​

Parse session logs into structured turns for analysis and processing.

# Parse latest log file
log-parser parse my-project

# Read specific turns
log-parser read my-project --last 5

# Watch in realtime
log-parser watch my-project

Repository: session-tools.ver2.log-parser

Architecture Diagram​

┌──────────────────────────────────────────────────────────────────┐
│                         User                                      │
└──────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐
│  logsession CLI  │ │   monitor    │ │   messenger      │
│  (start/list)    │ │   (web UI)   │ │   (send/approve) │
└──────────────────┘ └──────────────┘ └──────────────────┘
         │                   │               │
         ▼                   ▼               ▼
┌──────────────────────────────────────────────────────────────────┐
│                    ~/.loggable-session/logs/                      │
│                      (session log files)                          │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                   ┌──────────────────┐
                   │    log-parser    │
                   │  (parse turns)   │
                   └──────────────────┘

Installation​

All packages are available from the GitLab NPM registry via glpkg:

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

# Configure GitLab access (one-time setup)
gitlab-config save <your-gitlab-token>
gitlab-config scope set @session-tools microwiseai

# Install session-tools packages
gitlab-install @session-tools/loggable-session
gitlab-install @session-tools/logsession-monitor
gitlab-install @session-tools/session-messenger
gitlab-install @session-tools/log-parser

Session Tools works well with GitDot, a repository management dashboard that helps visualize and organize your GitLab/GitHub projects.

To view all Session Tools repositories:

  1. Go to GitDot Beta
  2. Select GitLab as the platform
  3. Enter microwiseai in the group field
  4. Click Load to see all repositories

License​

All packages are licensed under SSPL-1.0.

Copyright (C) 2024-2025 MicrowiseAI