Context Window Manager

The Problem

Your AI coding agent starts strong — remembers every architectural decision, every constraint, every file it touched. Two hours in, it's asking questions it already answered, violating rules you stated at the start, and generating code that contradicts the patterns it established. The context window filled up, and the agent silently degraded. You don't notice until it pushes a commit that reverts a key decision from 45 minutes ago.

What You Get

• Map your model's context budget with a per-model table (Claude 200K, GPT-5 1M, Gemini 1M) and rough token-cost formulas so you know exactly when compaction is needed
• Apply the compaction decision tree — at 50-70% use /compact with preservation rules, at 70-90% use targeted compaction, at 90%+ write a handoff doc and restart
• Write CLAUDE.md and AGENTS.md files under 200 lines that encode project conventions, architecture decisions, and active work — loaded every session start
• Declare scope boundaries before work begins — explicit SCOPE/OUT OF SCOPE blocks that prevent token waste on unrelated files
• Load files strategically — line-range loading (@file:src/module.py#L45-L80) instead of full-file dumps, with a token-cost calculator to estimate before loading
• Recover from context death with handoff documents that capture decisions, file changes, and next steps — so a fresh session picks up exactly where the last one left off

Why This Beats Prompting It Yourself

Without a system, you rely on the agent's "self-awareness" of its context usage — which doesn't exist. Agents don't monitor their own token consumption. They don't know they're about to lose constraints. This skill gives them a structured protocol: check the meter, compact at the right threshold, preserve what matters, discard what doesn't. The difference between a 2-hour session that stays coherent and one that falls apart at the 40-minute mark.

Example Session

You: "I'm about to start a refactoring session across 12 files in src/auth/"

Agent:

SCOPE: Refactoring src/auth/ module — 12 files, authentication flow
OUT OF SCOPE: src/api/, tests/, config files
Expected duration: ~90 minutes

Pre-flight checks:
- CLAUDE.md exists (87 lines) ✓
- Context usage: 8% ✓
- Will compact at 60% with preservation rules

Loading strategy:
1. Interface files first (auth/types.ts — 52 lines)
2. Callers (auth/middleware.ts#L1-L40)
3. Target files via line ranges only

Use Cases

• Long refactor sessions spanning 10+ files across multiple directories
• Multi-hour debugging sessions where constraint preservation is critical
• Sessions switching between unrelated tasks — proper /clear between context blocks
• Onboarding to an unfamiliar codebase where CLAUDE.md encodes tribal knowledge
• Batch code generation that would exhaust context if all files loaded at once
• Session handoff between team members using shared handoff documents

Known Limitations

This skill is a methodology, not a tool — it doesn't modify the agent's runtime or add context-window monitoring. You still need to manually track context usage or use agents that expose context meters. Some agents (older Cursor builds) don't support /compact with preservation instructions.

Upgrade to Pro

Free teaches awareness and handoff notes. Context Window Manager Pro ($5) makes compaction mechanical: five compression algorithms, a token budget tracker, and anchor templates that survive long refactors. Upgrade if your sessions compact more than twice a day — Pro version.