claude-compact-reminder

Auto-reminds you to /compact when your Claude Code context window is getting full.

Install

npx claude-compact-reminder

Restart Claude Code. The hook runs automatically on every prompt.

How It Works

A UserPromptSubmit hook that estimates context usage from the conversation transcript and tells Claude to suggest /compact when:

• Context usage exceeds 50% of the window
• Conversation exceeds 40 turns (tool calls inflate context beyond text)
• User says "new task", "moving on", etc. (signals a good compaction point)

Configuration

Set environment variables to customize thresholds:

export COMPACT_REMINDER_THRESHOLD=0.50         # 0.0-1.0 (default: 50%)
export COMPACT_REMINDER_CONTEXT_WINDOW=1000000  # total tokens (default: 1M)
export COMPACT_REMINDER_SYSTEM_OVERHEAD=100000   # system prompt tokens (default: 100K)

Prerequisites

• Claude Code v2.1.0+
• Python 3 (standard library only, no pip dependencies)

Uninstall

rm ~/.claude/hooks/compact-reminder.py

Then remove the compact-reminder entry from hooks.UserPromptSubmit in ~/.claude/settings.json.

License

MIT