Skip to main content

log-parser (Log Parsing)

log-parser parses Claude Code session logs into structured turn-based segments. It reads Claude's internal JSONL format and extracts human/assistant turns with timestamps.

Installation​

gitlab-install @session-tools/log-parser

Quick Start​

# Parse the latest log file
log-parser parse my-session

# Read specific turns
log-parser read my-session --turn 5
log-parser read my-session --last 3

# Watch for new turns in realtime
log-parser watch my-session

CLI Commands​

Parsing​

CommandDescription
log-parser parse <session>Parse latest log file (default)
log-parser parse <session> --allParse all log files
log-parser parse <session> --last <N>Parse last N files
log-parser parse <session> --date <YYYY-MM-DD>Parse files from specific date
log-parser parse <session> --from <date>Parse from date onwards
log-parser parse <session> --to <date>Parse files up to this date
log-parser parse <session> --forceRe-parse even if .parsed.jsonl exists

Reading​

CommandDescription
log-parser read <session>Read all turns
log-parser read <session> --turn <N>Read specific turn (1-indexed)
log-parser read <session> --turn <N-M>Read turn range (inclusive)
log-parser read <session> --last <N>Read last N turns
log-parser read <session> --from <N>Read from turn N onwards
log-parser read <session> --humanOnly human turns
log-parser read <session> --assistantOnly assistant turns
log-parser read <session> --format <type>Output format: 'full' (default) or 'simple'

Watching​

CommandDescription
log-parser watch <session>Watch single session
log-parser watch <s1> <s2> ...Watch multiple sessions

Utilities​

CommandDescription
log-parser list <session>List available log files

Usage Examples​

Parse and Read Workflow​

# 1. Parse the latest session log
log-parser parse my-project

# 2. Read all turns
log-parser read my-project

# 3. Read just the last conversation
log-parser read my-project --last 2

# 4. Read a specific turn
log-parser read my-project --turn 5

Filter by Role​

# See only what you asked
log-parser read my-project --human

# See only Claude's responses
log-parser read my-project --assistant

# Last 3 things Claude said
log-parser read my-project --last 3 --assistant

Turn Range​

# Read turns 3 to 7
log-parser read my-project --turn 3-7

# Read from turn 10 onwards
log-parser read my-project --from 10

# Last 3 human turns
log-parser read my-project --last 3 --human

Realtime Monitoring​

# Watch a session as it progresses
log-parser watch my-project

# Watch multiple sessions
log-parser watch frontend-task backend-task

# Output:
# [frontend-task] Watching: conversation_abc.jsonl
# [backend-task] Watching: conversation_xyz.jsonl
#   [frontend-task] → 2 new turn(s)
#   [backend-task] → 1 new turn(s)

Batch Processing​

# Parse all historical logs
log-parser parse my-project --all

# Parse logs from a specific date
log-parser parse my-project --date 2026-01-15

# Parse recent logs
log-parser parse my-project --last 5

# Parse date range
log-parser parse my-project --from 2026-01-01 --to 2026-01-15

Output Format​

Turn Output​

--- Turn 1 [human] 2026-01-15T10:30:00Z ---
Please implement user authentication

--- Turn 2 [assistant] 2026-01-15T10:30:15Z ---
I'll implement user authentication. Let me start by...

[Turns 1-2 of 15]

List Output​

Session: my-project
Path: ~/.loggable-session/logs/my-project

Log files (5):
  ✓ 2026-01-15_10-30-00.txt (latest)
  ✓ 2026-01-14_09-15-00.txt
    2026-01-13_14-20-00.txt
    2026-01-12_11-00-00.txt
    2026-01-11_08-45-00.txt

3/5 parsed

File Structure​

~/.loggable-session/logs/
└── my-project/
    ├── 2026-01-15_10-30-00.txt           # Raw terminal output
    ├── 2026-01-15_10-30-00.timestamps.json  # Timestamp data
    └── 2026-01-15_10-30-00.parsed.jsonl  # Parsed turns (JSONL)

Parsed Format (JSONL)​

Each line in .parsed.jsonl:

{"index": 0, "type": "human", "timestamp": "2026-01-15T10:30:00Z", "content": ["Please implement..."]}
{"index": 1, "type": "assistant", "timestamp": "2026-01-15T10:30:15Z", "content": ["I'll implement...", "..."]}

Integration with Other Tools​

  • daily-reporter: Aggregates parsed logs for daily reports
  • response-watcher: Monitors for new turns
  • session-detector: Detects session types

Version Info​

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