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 / Linuxls -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.
COMPACTION at line 47: 98234 -> 8102 tokens (8.2% retained)
COMPACTION at line 203: 112450 -> 9341 tokens (8.3% retained)
Verify: Each reported line number corresponds to a real turn boundary. Cross-check with sed -n '<line>p' "$SESSION_LOG" | jq .timestamp.
Step 4: Extract Timestamps for Each Compaction
For each compaction line number identified in Step 3, extract the ISO timestamp:
SESSION_LOG="<absolute-path-to-session.jsonl>"
COMPACTION_LINE=47 # Replace with actual line number# Extract timestamp from that JSONL line
sed -n "${COMPACTION_LINE}p""$SESSION_LOG" \
| grep -oP '"timestamp"\s*:\s*"\K[^"]+'
Alternative with jq:
sed -n "${COMPACTION_LINE}p""$SESSION_LOG" | jq -r '.timestamp // "unknown"'
Expected output:2026-03-21T14:32:07.441Z
Step 5: Compute Token Delta Per Compaction Event
For each compaction boundary, calculate:
tokens_before: input_tokens on the line immediately before the drop
Verify:compaction_count matches the number of events in the events array.
</execution_process>
<best_practices>
Always use absolute paths for SESSION_LOG — relative paths fail when the shell CWD differs.
Check file size before parsing — files >10MB should be processed line-by-line (streaming), not loaded into memory.
Threshold tuning — the default 50% drop threshold catches most compactions. Use 30% for aggressive detection or 70% for conservative (fewer false positives on large tool outputs).
Handle missing timestamps gracefully — not all JSONL lines include timestamp; fall back to line number as the event identifier.
Use python3 pipeline for production — the awk pipeline is fast for quick checks; the Python script is more reliable for malformed JSON or multi-byte characters.
