Record Post-Compaction Token Delta

On its own, a single compaction event means little. Logged consistently over time, the frequency becomes a signal — a project whose sessions compact unusually often is worth a look at why context keeps growing that fast.

Session Lifecycle & Continuity Event: PostCompact Claude Code Open source · Free

1. Save this as the hook script

#!/usr/bin/env python3
"""PostCompact hook — logs completion of a compaction event."""
import json, sys, datetime
from pathlib import Path

data = json.load(sys.stdin)
log_path = Path(data.get("cwd", ".")) / ".claude" / "compaction_log.jsonl"
log_path.parent.mkdir(parents=True, exist_ok=True)

entry = {"ts": datetime.datetime.utcnow().isoformat() + "Z",
         "session_id": data.get("session_id")}
with open(log_path, "a") as f:
    f.write(json.dumps(entry) + "\n")

sys.exit(0)

Save to a path inside your project, e.g. .claude/hooks/record-post-compaction-token-delta.sh, then chmod +x it.

2. Wire it into .claude/settings.json

{
  "hooks": {
    "PostCompact": [
      {
        "hooks": [
          {"type": "command", "command": "python3 .claude/hooks/record-post-compaction-token-delta.py"}
        ]
      }
    ]
  }
}

Before you use this

A hook runs with your local shell's permissions — review the script above before adding it, the same way you'd review any script you didn't write yourself. See our guide on hook security risks for the specific CVEs this category of feature has already produced.

Related hooks

Flag an Abnormal Session-End Reason
Logs session-end reason, and flags anything other than clean clear/resume/logout as worth…
Record Session Resume Cost Estimate
Logs the estimated cache-write cost and idle gap every time a session resumes.
Require a Clean Git Status Before Compaction
Blocks context compaction if the working tree has uncommitted changes.
Session-End Compliance Checklist Reminder
On explicit logout, checks for an open compliance TODO file and surfaces a reminder befor…
← All hooks
FEEDBACK