strategic-compact
Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction. Use when a session is approaching a context limit and a task phase is a natural place to compact.
- License 许可
- MIT
- 最近更新
- 2026-11-04
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- strategic-compact
- metadata
- { "origin": "ECC" }
- description
- Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction. Use when a session is approaching a context limit and a task phase is a natural place to compact.
03 SKILL.md 正文
Strategic Compact Skill
Suggests manual /compact at strategic points in your workflow rather than relying on arbitrary auto-compaction.
When to Activate
- Running long sessions that approach context limits (200K+ tokens)
- Working on multi-phase tasks (research → plan → implement → test)
- Switching between unrelated tasks within the same session
- After completing a major milestone and starting new work
- When responses slow down or become less coherent (context pressure)
Why Strategic Compaction?
Auto-compaction triggers at arbitrary points:
- Often mid-task, losing important context
- No awareness of logical task boundaries
- Can interrupt complex multi-step operations
Strategic compaction at logical boundaries:
- After exploration, before execution — Compact research context, keep implementation plan
- After completing a milestone — Fresh start for next phase
- Before major context shifts — Clear exploration context before different task
How It Works
The suggest-compact.js script runs on PreToolUse (Edit/Write) and combines two signals:
- Context size (primary) — Reads the latest
usagerecord from the session transcript (transcript_pathin the hook payload) and sumsinput_tokens + cache_read_input_tokens + cache_creation_input_tokens(the true context size of the turn). Suggests/compactat a window-scaled threshold — 160k tokens on a 200k window, 250k on a 1M window (detected from a[1m]model marker, or inferred when observed tokens already exceed 200k) — and re-reminds after every additional 60k tokens of context growth - Tool-call count (secondary) — Counts tool invocations in session; suggests at a configurable threshold (default: 50 calls), then every 25 calls after
Tool count alone is a weak proxy for window pressure: a few large file reads or MCP responses can fill the window in very few calls, while many tiny calls can cross 50 with a near-empty window. The context-size signal fires when it actually matters.
Hook Setup
Installed as a plugin? No setup is needed. The plugin's hooks/hooks.json already registers suggest-compact.js (hook id pre:edit-write:suggest-compact, active in the standard and strict hook profiles). Do not copy the block below into ~/.claude/settings.json — ~/.claude/scripts/ does not exist on plugin installs, and duplicating a plugin hook causes double execution.
If installed manually (./install.sh), add to your ~/.claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit",
"hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }]
},
{
"matcher": "Write",
"hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }]
}
]
}
}
Configuration
Environment variables:
COMPACT_THRESHOLD— Tool calls before first suggestion (default: 50)COMPACT_CONTEXT_THRESHOLD— Context tokens before the context-size suggestion (default: 160000 on a 200k window, 250000 on a 1M window;0disables the context signal)COMPACT_CONTEXT_INTERVAL— Additional context tokens before the suggestion repeats (default: 60000)COMPACT_STATE_TTL_DAYS— Days before stale per-session state files in the temp dir are swept (default: 14)ECC_CONTEXT_WINDOW_TOKENS— Explicit context-window size, in tokens, overriding auto-detection. Set this for large-window models whose reported id lacks a[1m]marker (e.g. 400k Opus 4.x, or a new 1M-window model family) so the threshold scales to the real window instead of defaulting to 200k and overstating context usage.CLAUDE_CODE_AUTO_COMPACT_WINDOW— Claude Code's native window-size override, in tokens; honored as a fallback whenECC_CONTEXT_WINDOW_TOKENSis unset.
The context window is otherwise auto-detected from a
[1m]model marker or inferred when observed tokens already exceed 200k. On a large-window model that carries neither signal, set one of the overrides above so the/compactsuggestion fires at the right point.
Compaction Decision Guide
Use this table to decide when to compact:
| Phase Transition | Compact? | Why |
|---|---|---|
| Research → Planning | Yes | Research context is bulky; plan is the distilled output |
| Planning → Implementation | Yes | Plan is in TodoWrite or a file; free up context for code |
| Implementation → Testing | Maybe | Keep if tests reference recent code; compact if switching focus |
| Debugging → Next feature | Yes | Debug traces pollute context for unrelated work |
| Mid-implementation | No | Losing variable names, file paths, and partial state is costly |
| After a failed approach | Yes | Clear the dead-end reasoning before trying a new approach |
What Survives Compaction
Understanding what persists helps you compact with confidence:
| Persists | Lost |
|---|---|
| CLAUDE.md instructions | Intermediate reasoning and analysis |
| TodoWrite task list | File contents you previously read |
Memory files (~/.claude/memory/) |
Multi-step conversation context |
| Git state (commits, branches) | Tool call history and counts |
| Files on disk | Nuanced user preferences stated verbally |
Best Practices
- Compact after planning — Once plan is finalized in TodoWrite, compact to start fresh
- Compact after debugging — Clear error-resolution context before continuing
- Don't compact mid-implementation — Preserve context for related changes
- Read the suggestion — The hook tells you when, you decide if
- Write before compacting — Save important context to files or memory before compacting
- Use
/compactwith a summary — Add a custom message:/compact Focus on implementing auth middleware next
Token Optimization Patterns
Trigger-Table Lazy Loading
Instead of loading full skill content at session start, use a trigger table that maps keywords to skill paths. Skills load only when triggered, reducing baseline context by 50%+:
| Trigger | Skill | Load When |
|---|---|---|
| "test", "tdd", "coverage" | tdd-workflow | User mentions testing |
| "security", "auth", "xss" | security-review | Security-related work |
| "deploy", "ci/cd" | deployment-patterns | Deployment context |
Context Composition Awareness
Monitor what's consuming your context window:
- CLAUDE.md files — Always loaded, keep lean
- Loaded skills — Each skill adds 1-5K tokens
- Conversation history — Grows with each exchange
- Tool results — File reads, search results add bulk
Duplicate Instruction Detection
Common sources of duplicate context:
- Same rules in both
~/.claude/rules/and project.claude/rules/ - Skills that repeat CLAUDE.md instructions
- Multiple skills covering overlapping domains
Context Optimization Tools
token-optimizerMCP — Automated 95%+ token reduction via content deduplicationcontext-mode— Context virtualization (315KB to 5.4KB demonstrated)
Related
- The Longform Guide — Token optimization section
- Memory persistence hooks — For state that survives compaction
continuous-learningskill — Extracts patterns before session ends
04 同仓库更多 Skills
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
youtube-downloader
Download YouTube videos with customizable quality and format options. Use this skill when the user asks to download, save, or grab YouTube videos. Supports various quality settings (best, 1080p, 720p, 480p, 360p), multiple formats (mp4, webm, mkv), and audio-only downloads as MP3.
theme-factory
Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.
template-skill
Replace with description of the skill and when Claude should use it.
tailored-resume-generator
Analyzes job descriptions and generates tailored resumes that highlight relevant experience, skills, and achievements to maximize interview chances
slack-gif-creator
Toolkit for creating animated GIFs optimized for Slack, with validators for size constraints and composable animation primitives. This skill applies when users request animated GIFs or emoji animations for Slack from descriptions like "make me a GIF for Slack of X doing Y".