compaction-detector

name	compaction-detector
description	Detect Claude Code context compaction events in session JSONL logs. Identifies compaction boundaries, measures token delta before/after, reports compaction events with timestamps and token impact.
version	1
model	sonnet
invoked_by	both
user_invocable	true
tools	["Read","Bash","Grep","TaskUpdate"]
verified	true
lastVerifiedAt	"2026-03-23T23:18:04.669Z"
best_practices	["Follow existing project patterns","Document all outputs clearly","Handle errors gracefully"]
error_handling	graceful
streaming	supported
source	builtin
trust_score	100
provenance_sha	4d2a925398265bc8

Compaction Detector

Compaction Detector Skill - Detect Claude Code context compaction events in session JSONL logs. Identifies compaction boundaries, measures token delta before/after, reports compaction events with timestamps and token impact. - Detect context compaction events in Claude Code session JSONL logs - Measure token delta (before/after) at each compaction boundary - Report compaction events with ISO timestamps, turn index, and token impact - Parse multi-session or single-session JSONL files - Output structured compaction report to stdout or file

Step 1: Locate the Session Log File

Claude Code session logs are stored as JSONL files. Find the target log:

# Default log location (adjust path for your OS)
# macOS / Linux
ls -lt ~/.claude/projects/*/logs/*.jsonl | head -5

# Windows (Git Bash / WSL)
ls -lt "/c/Users/$USER/.claude/projects/"*/logs/*.jsonl 2>/dev/null | head -5

# Or search by project path hash
find ~/.claude/projects -name "*.jsonl" -newer /tmp/sentinel 2>/dev/null

Expected output: One or more .jsonl file paths with modification timestamps. Verify: File is non-empty — wc -l <path> should return > 0.

Step 2: Identify Compaction Boundary Lines

Each line in a Claude Code session JSONL is a JSON object. Compaction events are identified by a sharp drop in usage.input_tokens between consecutive turns — the context was summarised and reset to a smaller window.

Command — extract token counts with line numbers:

SESSION_LOG="<absolute-path-to-session.jsonl>"

grep -n '"input_tokens"' "$SESSION_LOG" \
  | awk -F'[":,]' '{
      for(i=1;i<=NF;i++) {
        if($i ~ /input_tokens/) { print NR, $(i+2); break }
      }
    }'

Simpler alternative using jq (if available):

jq -r 'select(.usage.input_tokens != null) | [.timestamp, .usage.input_tokens, .usage.output_tokens] | @tsv' \
  

**Quick check — does this session have any compactions?**