Skip to main content

Getting Started

This guide covers installation and basic usage of Claude Session Tools.

Prerequisites​

Before installing Claude Session Tools, ensure you have:

  • Node.js 18 or later installed
  • tmux installed (for session management)

Installation​

The easiest way to get started is with the VSCode Extension. It automatically installs all dependencies for you.

  1. Open VSCode Extensions (Ctrl+Shift+X)
  2. Search for "Claude Session Tools"
  3. Click Install
  4. The extension will automatically install:
    • @session-tools/loggable-session
    • @session-tools/logsession-monitor

That's it! You're ready to use logsession commands.

See VSCode Extension for detailed features.

For Non-VSCode Users (CLI)​

Install using the glpkg installer:

# Install glpkg installer (public npm package)
npm install -g @glpkg/installer

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

The installer automatically handles npm registry configuration.

Verify Installation​

Check that the tools are installed correctly:

# Check logsession CLI
logsession --version

# Check monitor CLI
logsession-monitor --version

Basic Usage​

Step 1: Start a Claude Code Session​

Use logsession to start a Claude Code session with automatic logging:

# Start a new session (auto-generated name)
logsession start

# Or with a custom name
logsession start my-project

This creates a tmux session and begins logging all terminal output to ~/.loggable-session/logs/.

Step 2: Start the Monitor​

In a separate terminal, start the monitoring server:

logsession-monitor

Open your browser to http://localhost:5001 to access the web dashboard.

Step 3: Add Sessions to Monitor​

In the web interface:

  1. Click "Add Session" or use the input field
  2. Enter your session name (e.g., my-project)
  3. The session card appears showing real-time status

Step 4: Monitor Session Status​

Each session card displays:

  • Status: Current state (idle, active, waiting, stuck, dead)
  • Detail: Additional context about the activity
  • Health: Overall health indicator
  • Timestamp: Last update time

Step 5: Configure Notifications (Optional)​

Click the settings icon on a session card to configure:

  • Enable/disable waiting notifications
  • Enable/disable idle notifications
  • Set threshold durations
  • Adjust volume

Quick Reference​

logsession Commands​

logsession start [name]     # Start a new session
logsession list             # List all sessions
logsession show <name>      # View session logs
logsession attach <name>    # Attach to a detached session
logsession stop <name>      # Stop a session

logsession-monitor Commands​

logsession-monitor          # Start monitor server
logsession-monitor list     # List all sessions
logsession-monitor watch <name>    # Watch a session
logsession-monitor status          # Show status of watched sessions

tmux Shortcuts (while in a session)​

ShortcutAction
Mouse wheelScroll up/down
Ctrl+B [Enter copy mode (arrow keys, PgUp/PgDn, 'q' to exit)
Ctrl+B DDetach from session (keeps running)
Ctrl+D or exitEnd session

Directory Structure​

~/.loggable-session/
├── config.json          # Global configuration
├── profiles/            # Custom profiles
└── logs/
    └── <session-name>/
        └── <timestamp>.txt   # Session log files

Troubleshooting​

"Command not found" after installation​

Ensure your npm global bin directory is in your PATH:

# Check npm bin location
npm config get prefix

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$(npm config get prefix)/bin"

Session not detected in monitor​

  1. Verify the session exists: logsession list
  2. Check logs directory: ls ~/.loggable-session/logs/
  3. Ensure the session was started with logsession, not plain tmux

Next Steps​