| name | context-budget |
| description | Manage Claude Code's context window to avoid performance degradation — monitor, assess, and compact at the right moment. Use this skill when responses feel slower or less accurate, when planning a long multi-file session, when switching between major tasks, or when tempted to compact mid-debugging or mid-implementation. Also use when the user mentions "context", "window", "slow", "compact", or "running out of space". Helps decide WHEN to compact, what to keep, and what is dangerous to lose. |
Context Budget
Manage Claude Code's context window to avoid degraded performance in long sessions. Context is finite — every file you read, every command you run, and every response you generate consumes it. Planning how to spend it is as important as planning the code itself.
When to Use
- At the start of complex tasks (plan context usage)
- When responses start feeling slower or less accurate
- Before starting a new major subtask
- When switching from one major task to another
- After completing and committing a feature
- When a session has exceeded 200+ tool calls
Token Estimation
Rough guide for planning how much context a task will consume:
| Content | Approximate Tokens |
|---|
| 1 KB of text | ~250 tokens |
| Typical .ts file (50-150 lines) | 500-2,000 tokens |
| Large module (300+ lines) | 3,000-6,000 tokens |
| Full test file | 1,000-3,000 tokens |
| A skill document (~80 lines) | ~800 tokens |
| Each tool call + response | 200-1,000 tokens |
| A git diff (medium PR) | 2,000-5,000 tokens |
Use these estimates to decide whether you can afford to read "one more file" or if you should compact first.
How It Works
- Monitor — Use /kompact audit to check context usage
- Assess — Evaluate what is critical vs expendable in current context
- Decide when — Use the timing guide below
- Compact — Use /kompact for guided compaction with audit and safety checks
- Reload — Re-read critical files after compaction
Pre-Session Planning
Before starting a complex task, estimate which files you will need and in what order. This prevents mid-task compaction, which is the most dangerous kind.
Task: "Add a new instinct export format"
Files needed:
- scripts/lib/types.ts (interface shapes) ~800 tokens
- scripts/lib/instinct-manager.ts (existing logic) ~1500 tokens
- tests/lib/instinct-manager.test.ts (test patterns) ~2000 tokens
- scripts/lib/state-store.ts (query layer) ~2000 tokens
Estimated total: ~6300 tokens for reading alone
Plan: read types first, then instinct-manager, then write test, then implement
Multi-File Session Strategy
When working across many files, batch your work to minimize context pressure:
- Group related files — read types.ts + implementation + test together, not scattered
- Complete one module before starting another — finish, test, commit, then move on
- Commit between modules — this creates safe compaction points
- Defer unrelated reads — if you see something interesting in another module, note it but do not read it yet
When to Compact
Good times (safe)
- After a commit (work is saved)
- After completing a file implementation (tests pass)
- Before switching from library code to hook code
- After a research/analysis phase, before implementation
- Between major implementation phases
Bad times (dangerous)
- Mid-implementation of a multi-file feature
- While holding context about cross-file dependencies
- Before committing (you will forget what changed)
- During debugging (you will lose the error trail)
- Mid-research when cross-file connections matter
Rule of thumb: if in doubt, do not compact — slightly slower is better than losing context.
Reload Priority After Compaction
After compacting, you lose all file contents. Re-read in this order because each layer builds on the previous:
- types.ts — interface shapes that everything depends on (always first)
- The file you are actively editing — restore working context
- The test file for that module — remember what behavior is expected
- Adjacent files — only if cross-file dependencies matter for the current task
Do NOT re-read files you are done with. The whole point of compaction is to shed context you no longer need.
Examples
Example 1: Long implementation session
Session plan:
1. Implement utils.ts (small) — no compact needed
2. Implement state-store.ts (large) — compact AFTER, before next file
3. Implement session-manager.ts (medium) — uses state-store, keep in context
4. Compact before switching to hook implementation
Example 2: Context-heavy research
Reading 10 source files for analysis -> compact after producing the analysis
Don't compact mid-research — you'll lose the cross-file connections
Example 3: Bug investigation
Found bug in file A, traced cause to file B -> DO NOT compact
Fix -> test -> commit -> THEN compact safely
Anti-Patterns
- Compacting mid-debug — You traced a bug through 4 files and now compact to "free up space." You just erased the trail. Fix first, compact after.
- Reading every file "just in case" — Each unnecessary read burns context. Use Grep to find the right file, then read only that file.
- Never compacting — Eventually quality degrades. Compact proactively at safe points rather than waiting for degradation.
- Re-reading everything after compaction — Only reload what the current task needs. Compaction is an opportunity to shed old context.
Integration
- /kompact command implements this skill (full flow: audit + safety + summarize + compact guidance)
- /kompact audit subcommand for quick context usage checks without compacting
- pre-compact-save hook automatically saves session state and pending tasks before compaction
- session-start hook restores 3 recent sessions with history trajectory and pending work carry-forward
- /context-budget command audits current context window usage
Rules
- Compact at natural breakpoints (between features, not mid-implementation)
- Never compact while holding uncommitted work context
- After compaction, re-read critical files (types.ts, the file you are editing)
- Use /kompact for guided compaction with audit and safety checks
- Compact after commits, not before
- Plan context usage before starting complex multi-file tasks
no_context Application
Context budget management prevents the scenario where Claude "forgets" earlier context and starts inventing. By compacting strategically and re-reading critical files, the no_context principle is maintained even in long sessions. The pre-compact-save hook preserves state and pending tasks, and the session-start hook restores 3 recent sessions with trajectory and pending work in the next session.
