Claude Code Context Guard

Never lose context mid-conversation again.

A 3-layer early warning system that alerts you before Claude Code auto-compacts your conversation. Know exactly when to /compact on your own terms — preserving the context that matters.

The Problem

Claude Code auto-compacts your conversation when it hits the autoCompactWindow threshold (default: 200K tokens). When that happens:

• Your conversation history is replaced with a summary
• Skill descriptions are not re-injected
• Active context about your task can be lost
• You had no warning it was coming

Manual /compact lets you control what gets preserved. But you need to know when to do it.

The Solution

Three layers of defense, zero configuration loops, always-on:

 Layer 1: Statusline        → Visual % with escalating indicators
 Layer 2: PreCompact Hook   → Sound + macOS notification at threshold  
 Layer 3: CLAUDE.md Rule    → AI proactively warns you at 70%+

What It Looks Like

# Normal (< 70%)
Opus 4.6 | 45200 tk | window 42% | used 15% | resets 3h20m

# Warning (70-84%)
Opus 4.6 | 98000 tk | 🟡 window 73% | used 30% | resets 2h05m

# Critical (85%+)
Opus 4.6 | 130000 tk | 🔴 COMPACT NOW 87% | used 42% | resets 1h15m

At 85%+, the statusline screams. If auto-compaction triggers anyway, you get a system sound (Sosumi) and a macOS notification.

Installation

1. Statusline Script

Copy statusline.sh to ~/.claude/:

curl -o ~/.claude/statusline.sh https://raw.githubusercontent.com/lincpek-bot/claude-code-context-guard/main/statusline.sh
chmod +x ~/.claude/statusline.sh

2. Settings Configuration

Add these to your ~/.claude/settings.json (see settings-example.jsonc for the full snippet):

{
  // Point statusline to the script
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },

  // Set your compaction threshold (default 200K, we use 150K)
  "autoCompactWindow": 150000,

  // Add the PreCompact hook inside your existing "hooks" object
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Sosumi.aiff && osascript -e 'display notification \"Context at compaction threshold — /compact manually if needed\" with title \"⚠️ Claude Compacting\"'",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

3. CLAUDE.md Rule (Layer 3)

Add this to your ~/.claude/CLAUDE.md (see claude-md-snippet.md):

## Compaction Awareness

When context window reaches **70%+**, proactively warn the user: state the
current %, recommend `/compact`, and note what context to preserve. At **85%+**,
make it the FIRST thing you say in your response. Statusline shows live % with
color indicators; PreCompact hook plays Sosumi + macOS notification when
auto-compaction triggers.

How It Works

Layer	Trigger	What Happens
Statusline	Every message	Shows window X% with escalating indicators
PreCompact Hook	Auto-compaction fires	Plays Sosumi sound + macOS notification
CLAUDE.md Rule	70%+ context usage	Claude proactively warns you to /compact

The statusline calculates context % relative to your autoCompactWindow setting, not the full model context. This gives you an accurate read on how close you are to the threshold that actually matters.

Customization

Change thresholds

Edit the tier boundaries in statusline.sh:

if [ "$ctx_pct" -ge 85 ]; then    # Critical — change to your preference
  ctx_label="🔴 COMPACT NOW ${ctx_pct}%"
elif [ "$ctx_pct" -ge 70 ]; then   # Warning — change to your preference  
  ctx_label="🟡 window ${ctx_pct}%"

Change the compaction window

In settings.json, adjust autoCompactWindow. Lower = more aggressive compaction:

"autoCompactWindow": 120000  // Compacts earlier, gives you more runway

Change the alert sound

Swap Sosumi.aiff for any sound in /System/Library/Sounds/:

ls /System/Library/Sounds/  # See all available sounds

Linux / non-macOS

Replace the PreCompact hook command:

# Linux with notify-send + paplay
"command": "paplay /usr/share/sounds/freedesktop/stereo/alarm-clock-elapsed.oga && notify-send 'Claude Compacting' 'Context at threshold — /compact manually'"

Requirements

• Claude Code CLI
• jq (for JSON parsing in statusline)
• macOS (for afplay + osascript notifications) — see Linux alternative above

License

MIT