strategic-compact

Strategic Compact Skill

It is recommended to manually execute at strategic points in the workflow /compact, rather than relying on random automatic compaction.

When to Activate

When running long sessions that approach the context limit (200K+ tokens)
When handling multi-stage tasks (research → planning → implementation → testing)
When switching between unrelated tasks in the same session
After completing a major milestone and starting new work
When responses become slower or coherence decreases (context pressure)

Why Strategic Compaction?

Automatic compaction triggers at arbitrary points:

It often triggers mid-task, causing important context to be lost
It cannot recognize logical task boundaries
It may interrupt complex multi-step operations

Perform strategic compaction at logical boundaries:

After research, before implementation — Compact the research context and preserve the implementation plan
After completing a milestone — Provide a fresh starting point for the next stage
Before a major context switch — Clear exploratory context before moving on to a different task

How It Works

suggest-compact.js The script runs on tool pre-invocation (PreToolUse, including Edit/Write) and performs:

Track tool calls — Count the number of tool calls in the session
Threshold detection — Provide suggestions when a configurable threshold is reached (default: 50 calls)
Periodic reminders — After exceeding the threshold, remind once every 25 calls

Hook Setup

Add the following to your ~/.claude/settings.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
      },
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
      }
    ]
  }
}

Configuration

Environment variables:

COMPACT_THRESHOLD — Number of tool calls before the first suggestion (default: 50)

Compaction Decision Guide

Refer to the table below to decide when to compact:

Stage Transition	Compact?	Reason
Research → Planning	Yes	The research context is bloated; the plan is the refined output
Planning → Implementation	Yes	The plan has been recorded in `TodoWrite` or files; free up context space for code
Implementation → Testing	It depends	Keep it if the tests reference recent code; compact if switching focus
Debugging → Next feature	Yes	Debugging traces pollute the context for unrelated work
During implementation	No	The cost of losing variable names, file paths, and partial state is high
After a failed attempt	Yes	Clear out the dead-end reasoning before trying a new approach

What Survives Compaction

Understanding what persists lets you compact with confidence:

Survives	Lost
`CLAUDE.md` CLUADE.md instructions	Intermediate reasoning and analysis process
`TodoWrite` Task list	Contents of previously read files
Memory files (`~/.claude/memory/`)	Multi-turn conversation context
Git status (commits, branches)	Tool call history and counts
Files on disk	Subtle user preferences stated verbally

Best Practices

Compact after planning — once the plan is determined in TodoWrite , compact to start over
Compact after debugging — clean up the context of resolved errors before continuing
Do not compact mid-implementation — preserve context for related changes
Reading suggestions — the hook tells youwhenyou can compact; it is up to youwhetherto execute
Write before compacting — save important context to a file or memory before compacting
Use /compact with a summary — add a custom message:/compact Focus on implementing auth middleware next

The Longform Guide — Token optimization chapter
Memory persistence hook — for state that survives after compaction
continuous-learning skill — extract patterns before the session ends

About this skill