session

CLI for parsing and browsing Claude Code session files (.jsonl).

Features

• Parse sessions: Convert .jsonl session files to readable formats (narrative, terminal, markdown)
• Interactive browser: Browse sessions with fzf, preview content, resume sessions
• Session discovery: Find sessions by ID prefix, filter by date/project
• Streaming mode: Parse sessions in real-time from stdin
• Subagent support: Include subagent transcripts in output

Installation

Requires Bun:

git clone https://github.com/nitsanavni/session.git
cd session
bun install

Usage

Parse a session

# Basic narrative output
bun src/cli.ts <session.jsonl>

# By session ID (searches ~/.claude/projects/)
bun src/cli.ts 502de9c7

# Terminal format (replicates Claude's /export)
bun src/cli.ts session.jsonl --format terminal

# Markdown format
bun src/cli.ts session.jsonl --format markdown

# Include tool inputs/outputs
bun src/cli.ts session.jsonl --tool-input --tool-output

# Include subagent transcripts
bun src/cli.ts session.jsonl --subagents

Browse sessions interactively

# Open fzf browser with preview
bun src/cli.ts find

# Filter by date
bun src/cli.ts find --since 1d    # last day
bun src/cli.ts find --since 2w    # last 2 weeks

# All projects (not just current)
bun src/cli.ts find --all-projects

Keybindings in fzf:

• Enter - output session path
• Ctrl-R - resume session with claude --resume
• Ctrl-E - export to markdown file
• Ctrl-T - push to retro (requires RETRO_SCRIPT env var)

List sessions

# List recent sessions
bun src/cli.ts list

# Limit results
bun src/cli.ts list -n 5

# Output as JSON
bun src/cli.ts list --output json

Stream mode

# Parse from stdin in real-time
tail -f session.jsonl | bun src/cli.ts --stream

# Pipe from claude
claude -p "hello" --output-format stream-json | bun src/cli.ts --stream

Session location

Sessions are stored at ~/.claude/projects/<project-hash>/*.jsonl by Claude Code. The project hash is derived from your working directory path.

Options reference

OPTIONS:
  --format <fmt>     Output format: narrative (default), terminal, markdown
  --stream           Stream mode: read from stdin, output in real-time
  --tool-input       Include tool call inputs
  --tool-output      Include tool results
  --truncate <n>     Truncate tool I/O to n chars (default: 500)
  --subagents        Include subagent transcripts (appended at end)
  --include-warmups  Include warmup subagents (excluded by default)
  --list-files       List all related files (main + subagents), one per line
  --help, -h         Show help

LIST/FIND OPTIONS:
  --limit, -n <n>    Limit results (default: 10)
  --project <hash>   Filter to specific project
  --all-projects     Show sessions from all projects
  --output <format>  Output format: path, id, json
  --since <filter>   Filter by date (1d, 2w, 2024-01-15)

Environment variables

• CLAUDE_BIN - Path to claude executable (default: claude)
• VSC_BIN - Path to vsc-bridge executable (default: vsc)
• RETRO_SCRIPT - Path to a script to run when pressing Ctrl-T in the browser (optional)

License

MIT