Claude Compact Controller

Smart auto-compact management for Claude Code. Prevents context loss during compaction by saving vault backups of conversation state and injecting references post-compact.

Problem

When Claude Code auto-compacts, it summarizes the conversation to free up context window space. This can cause Claude to lose track of what it was working on — files it edited, decisions it made, or multi-step operations in progress.

How It Works

Three hooks work together to wrap the auto-compact lifecycle:

1. Stop Hook — fires after every Claude response. Tracks cumulative token usage, turn count, and session metadata in a persistent state file.

2. PreCompact Hook — fires right before auto-compaction. Reads the conversation transcript tail and saves it to a timestamped vault file. Injects a message telling Claude the vault was saved.

3. PostCompact Hook — fires right after compaction finishes. Injects a message pointing Claude to the vault file so it can recover any lost context by reading it.

Normal operation:        Stop hook tracks tokens each turn
                              |
Auto-compact triggers:   PreCompact saves vault backup
                              |
Compact runs:            Conversation is summarized
                              |
Post-compact:            PostCompact injects vault reference
                              |
Claude continues:        Can read vault file if context was lost

Install

cd ~/claude-compact-controller
node install.js

This adds three hooks to your user-level ~/.claude/settings.json. Existing hooks are preserved — it only appends. Restart Claude Code after installing.

Uninstall

node uninstall.js

Removes the hooks from settings. Vault data is preserved for manual cleanup.

Check Status

node status.js

Shows current token tracking state and lists all vault backups.

Configuration

Edit config.json:

Key	Default	Description
vault_max_entries	10	Max vault backups to keep (oldest pruned first)
vault_transcript_tail_bytes	50000	Bytes of transcript tail to save per vault (~12k tokens)
log_enabled	false	Enable debug logging to ~/.claude/compact-controller/controller.log

File Layout

claude-compact-controller/          # This repo
├── hooks/
│   ├── stop-hook.js                # Token tracking (Stop event)
│   ├── pre-compact.js              # Vault backup (PreCompact event)
│   └── post-compact.js             # Vault reference injection (PostCompact event)
├── lib/
│   └── shared.js                   # Shared utilities
├── config.json                     # Configuration
├── install.js                      # Hook installer
├── uninstall.js                    # Hook remover
└── status.js                       # Status checker

~/.claude/compact-controller/       # Runtime data (created automatically)
├── state.json                      # Current session tracking
├── controller.log                  # Debug log (if enabled)
└── vault/
    ├── vault-2026-05-21T14-30-00-000Z.json
    └── ...                         # Timestamped vault backups

Vault Format

Each vault file contains:

{
    "timestamp": "2026-05-21T14:30:00.000Z",
    "session_id": "abc123",
    "trigger": "auto-compact",
    "context_tokens": 185000,
    "output_tokens_total": 42000,
    "turn_count": 47,
    "cwd": "/path/to/project",
    "transcript_tail": "... last ~50KB of conversation ..."
}

Requirements

• Claude Code (with hook support)
• Node.js (ships with Claude Code)