affaan-m/ecc

strategic-compact

Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/affaan-m/ecc --skill strategic-compact

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

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:

  1. Context size (primary) — Reads the latest usage record from the session transcript (transcript_path in the hook payload) and sums input_tokens + cache_read_input_tokens + cache_creation_input_tokens (the true context size of the turn). Suggests /compact at 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. A valid native compaction budget can lower the default reminder threshold to 80% of that budget; model-capacity percentages still use the resolved model window
  2. 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:

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, capped at 80% of a valid native compaction budget when earlier). An explicit positive threshold overrides that default cap; 0 disables 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 auto-compact trigger, which may be smaller than the model's context window. For context-window resolution, ECC uses it only as a last-resort fallback, after an explicit ECC override, a [1m] model marker, a known large-window model family, and inference from observed tokens above 200k. It is not an exact model-capacity declaration.
Window precedence is: ECC_CONTEXT_WINDOW_TOKENS, then the [1m] marker, a known large-window model family, observed tokens above 200k, the native auto-compact fallback, and finally the inferred 200k default. Set ECC_CONTEXT_WINDOW_TOKENS when you know the actual window and automatic detection lacks that information; do not treat the native compact trigger as proof of model capacity.

The Stop-hook summary scheduler protects resume state before compaction. It uses the earlier of confirmed capacity and a valid native compaction budget. When capacity is inferred, it uses only a valid native budget, or treats the remaining budget as unknown if none is provided. Model-capacity resolution remains separate. The default /compact reminder threshold independently uses the earlier of its window-scaled default and 80% of a valid native compaction budget. An explicit COMPACT_CONTEXT_THRESHOLD, including 0, remains authoritative.

Compaction Decision Guide

Use this table to decide when to compact:

Phase TransitionCompact?Why
Research → PlanningYesResearch context is bulky; plan is the distilled output
Planning → ImplementationYesPlan is written down (a file, or the task list if you have one); free up context for code
Implementation → TestingMaybeKeep if tests reference recent code; compact if switching focus
Debugging → Next featureYesDebug traces pollute context for unrelated work
Mid-implementationNoLosing variable names, file paths, and partial state is costly
After a failed approachYesClear the dead-end reasoning before trying a new approach

What Survives Compaction

Understanding what persists helps you compact with confidence:

PersistsLost
CLAUDE.md instructionsIntermediate reasoning and analysis
Files on diskFile contents you previously read
Memory files (~/.claude/memory/)Multi-step conversation context
Git state (commits, branches)Tool call history and counts
The task list — only if you have the todo tools (see below)Nuanced user preferences stated verbally
### Don't rely on the task list surviving — it may not exist Claude Code 2.1.233 removed the todo/task tools by default on Opus 4.8, Sonnet 5, Fable 5, Mythos 5 and newer models (TodoWrite, TaskCreate/Get/Update/List). CLAUDE_CODE_ENABLE_TODO_TOOLS=1 brings them back, but that is a per-machine environment setting — it does not travel with this skill, so you cannot assume the reader has it. This matters because "my todo list survives compaction" is a reason people compact instead of writing state down. If the tools are absent there is no list to survive, and the plan is simply gone. Write the plan to a file before compacting — a file persists on every version and every model. Treat the task list as a convenience that may be missing, never as your durable record.

Best Practices

  1. Compact after planning — Once the plan is finalized and written to a file, compact to start fresh
  2. Compact after debugging — Clear error-resolution context before continuing
  3. Don't compact mid-implementation — Preserve context for related changes
  4. Read the suggestion — The hook tells you when, you decide if
  5. Write before compacting — Save important context to files or memory before compacting
  6. Use `/compact` with 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%+:

TriggerSkillLoad When
"test", "tdd", "coverage"tdd-workflowUser mentions testing
"security", "auth", "xss"security-reviewSecurity-related work
"deploy", "ci/cd"deployment-patternsDeployment 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-optimizer MCP — Automated 95%+ token reduction via content deduplication
  • context-mode — Context virtualization (315KB to 5.4KB demonstrated)

Related

  • The Longform Guide — Token optimization section
  • Memory persistence hooks — For state that survives compaction
  • continuous-learning skill — Extracts patterns before session ends
du même dépôt

Autres Skills

Tous les Skills
affaan-m
Communauté

rust-testing

Rust testing patterns including unit tests, integration tests, async testing, property-based testing, mocking, and coverage. Follows TDD methodology. Use when writing Rust tests — unit, integration, async, property-based, or coverage.

Installations / 24h
489
GitHub Stars
308,2 k
Mis à jour
20 nov.
affaan-m
Communauté

search-first

Research-before-coding workflow: search npm/PyPI, MCP servers, skills, and GitHub for existing tools before writing custom code, then adopt, extend, or build. Launches the researcher agent for non-trivial needs. Use when starting a feature, adding a dependency or integration, or about to write a utility that may already exist.

Installations / 1h
5
GitHub Stars
308,2 k
Mis à jour
20 nov.
affaan-m
Communauté

browser-qa

Run automated post-deploy UI verification with a browser automation MCP (claude-in-chrome, Playwright, or Puppeteer): console-error and Core Web Vitals smoke checks, form and auth-flow interaction tests, screenshot visual regression across three breakpoints, and axe-core accessibility audits ending in a SHIP / DO-NOT-SHIP verdict. Use when testing a deployed feature on staging or preview, before shipping frontend changes, reviewing a frontend PR, or checking responsive layout and accessibility.

Installations / 1h
2
GitHub Stars
307,9 k
Mis à jour
20 nov.
affaan-m
Communauté

docker-patterns

Docker and Docker Compose patterns for local development, hardened CLI installer harnesses, container security, networking, volumes, and multi-service orchestration. Use when creating or reviewing Dockerfiles and Compose services, testing installers across Linux distributions, or planning accurate native macOS and Windows validation.

Installations / 1h
2
GitHub Stars
307,9 k
Mis à jour
20 nov.