Skip to main content

logsession (Core)

logsession is the core tool for automatically logging Claude Code sessions. It runs Claude Code within a tmux session and records all terminal output.

Installation​

gitlab-install @session-tools/loggable-session

Quick Start​

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

# Start with a specific name
logsession start my-project

# Start in the background
logsession start my-project --detach

# Resume previous Claude session
logsession start my-project --resume

CLI Commands​

Session Management​

CommandDescription
logsession start [name] [options]Start a new session (default: auto-attach)
logsession list [options]List all sessions
logsession show <name> [options]View session logs
logsession attach <name>Reattach to a detached session
logsession stop <name>Stop a session
logsession delete <name>Delete a session (stop + remove logs)
logsession rename <old> <new>Rename a session
logsession capture <name> [options]Capture tmux pane content

Configuration Management​

CommandDescription
logsession configShow current configuration
logsession config showShow current configuration
logsession config set <key> <value>Set configuration value
logsession config resetReset to defaults

Profile Management​

CommandDescription
logsession profile listList all profiles
logsession profile show <name>Show profile details
logsession profile create <name> [opts]Create a new profile
logsession profile delete <name>Delete a profile

Miscellaneous​

CommandDescription
logsession infoShow app information
logsession initInitialize app directory
logsession examplesView usage examples
logsession helpShow help
logsession --version, -vShow version

Key Options​

start Command Options​

logsession start [name] [options]

Options:
  --detach, -d                      Start in the background
  --show-context, -c                Automatically send previous logs to Claude
  --resume, -r [logfile]            Resume previous Claude session
                                    (omit logfile for most recent)
  --profile, -p <name>              Use a profile (model, system-prompt)
  --system-prompt <prompt>          Direct system prompt (overrides profile)
  --claude-session-id <uuid>        Specify Claude Code session ID (UUID)
  --allowedTools, --allowed-tools   Comma-separated allowed tools
                                    (merged with profile.allowedTools)

list Command Options​

logsession list [options]

Options:
  --json, -j              Output in JSON format
  --profile, -p <name>    Filter by profile name
  --help, -h              Show help for this command

show Command Options​

logsession show <session-name> [options]

Options:
  --json, -j              Output in JSON format (includes uuid)
  --help, -h              Show help for this command

capture Command Options​

logsession capture <session-name> [options]

Options:
  -n <lines>              Number of lines to capture (default: 100, max: 1000)
  --limitless             Remove the 1000 line limit
  --help, -h              Show help for this command

Usage Examples​

Basic Usage​

# Start and enter a session
logsession start my-task

# Start in the background
logsession start my-task --detach

# Reattach later
logsession attach my-task

Resume Previous Work​

# Resume last Claude session (full context)
logsession start my-task --resume
logsession start my-task -r  # Short form

# Resume specific log file's session
logsession start my-task --resume 2026-01-15_17-00-00.txt

# Auto-send previous logs to Claude
logsession start my-task --show-context
logsession start my-task -c  # Short form

Using Profiles​

# Create a profile with system prompt
logsession profile create dev --system-prompt "You are a dev assistant"

# List all profiles
logsession profile list

# Show profile details
logsession profile show dev

# Start a session with a profile
logsession start my-task --profile dev
logsession start my-task -p dev  # Short form

Direct System Prompt​

# Direct system prompt (no profile needed)
logsession start my-task --system-prompt "You are a code reviewer"

Using Allowed Tools​

# Specify allowed tools directly
logsession start my-task --allowedTools 'Edit,Write,Bash(npm *)'

# Merge with profile's allowedTools
logsession start my-task -p dev --allowedTools 'Bash(docker *)'

Adjusting Configuration​

# Check current configuration
logsession config

# Adjust update interval (default: 200ms)
logsession config set interval 100   # Ultra-responsive (higher CPU)
logsession config set interval 200   # Fast, most efficient (default)
logsession config set interval 500   # Battery-friendly

# Reset to defaults
logsession config reset

Managing Sessions​

# List all sessions (text format)
logsession list

# List sessions in JSON format
logsession list --json

# Filter sessions by profile
logsession list --profile dev
logsession list -p dev --json

Capturing Tmux Pane Content​

# Capture last 100 lines (default)
logsession capture my-session

# Capture last 500 lines
logsession capture my-session -n 500

# Capture more than 1000 lines (requires --limitless)
logsession capture my-session -n 2000 --limitless

Configuration Options​

Available processor types:

TypeDescription
pipe-stdinpipe-pane → stdin (recommended, no raw file)
pipe-rawpipe-pane → raw file → processor
capture-intervaltmux capture-pane on interval (legacy)
optimized-captureSmart adaptive polling (1-10s, low CPU) [default]

Interval values:

IntervalDescription
100msVery responsive (~15% CPU)
200msFast, most efficient (~12% CPU) [default]
500msBalanced (~14% CPU)
1000msConservative (~13% CPU)

tmux Shortcuts​

While attached to a session:

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

Log File Location​

~/.loggable-session/
├── config.json          # Global configuration
├── profiles/            # Saved profiles (*.json)
├── sessions/            # Session metadata
├── io-logs/             # I/O logs (JSONL)
└── logs/
    └── <session-name>/
        └── <timestamp>.txt   # Log files

Integration with Other Tools​

Logs created by logsession can be used with other Session Tools:

  • logsession-monitor: Real-time session status monitoring
  • log-parser: Parse logs into structured turns
  • session-messenger: Inter-session messaging
  • sesh: Extended CLI with session config management

Version Info​

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