javimosch Claude Session Optimizer
Claude Code sessions (~/.claude/projects/*/*.jsonl) grow unbounded. Once a session exceeds ~75 MB, Claude crashes on load. This tool compresses them back to < 50 MB while keeping conversation history intact.
Quick Start
🔍 One-command health check (safe)
# First-time: sync latest plugins, install, and run health check
sc plugins update && sc plugins install claude-session-optimizer
sc claude-session-optimizer self auto
The auto command auto-installs the optimizer (cached), scans all sessions, reports oversized ones, and tells you how to compress. Never modifies files — safe to run anytime.
Note for npx users: Replace
scwithnpx superacli. Theplugins updatecommand fetches the latest plugin catalog directly from GitHub — no npm publish needed.
Manual commands
# List all sessions with sizes
sc claude-session-optimizer self list
# Compress all sessions over 50 MB
sc claude-session-optimizer self compress
# Preview savings (no writes)
sc claude-session-optimizer self dry-run
# Target a specific session
sc claude-session-optimizer self file --path ~/.claude/projects/-my-project/uuid.jsonl
# Custom threshold (e.g., 30 MB)
sc claude-session-optimizer self compress-threshold --threshold 30
What Gets Removed
| Component | Why | Typical savings |
|---|---|---|
| thinking blocks | Internal reasoning (not needed to continue) | ~11 MB |
| file-history-snapshots | Undo history (auto-rebuilt) | ~17 MB |
| pr-link, queue-operation | Redundant metadata | ~1 MB |
| tool_result (large) | Command output → [truncated: N B] |
~3 MB |
| tool_use input (large) | Tool args → tool name + size note | ~4 MB |
Kept: user messages, assistant text, attachments/goals, system prompts, last-prompt, mode markers.
Installation
mkdir -p ~/.local/bin
curl -sL https://raw.githubusercontent.com/javimosch/claude-session-optimizer/main/compress-claude-session.py -o ~/.local/bin/compress-claude-session
chmod +x ~/.local/bin/compress-claude-session
Or run directly without installing:
python3 <(curl -sL https://raw.githubusercontent.com/javimosch/claude-session-optimizer/main/compress-claude-session.py) --list
Safety
- Creates
.bakbackup before modifying any file - Idempotent: running on already-compressed session is a no-op
- Dry-run: use
--dry-runto preview - Zero dependencies: Python 3 standard library only