| name | token-budget |
| description | Context window management — track spend, decide when to compact, preserve state |
| version | 0.1.0 |
| level | 2 |
| triggers | ["context getting long","token budget","should we compact","running out of context","context window"] |
| context_files | ["context/learnings.md","context/project.md"] |
| steps | [{"name":"Assess","description":"Estimate current context usage and how much remains"},{"name":"Triage","description":"What must be preserved vs. what can be safely dropped?"},{"name":"Pre-Compact Capture","description":"Write critical state to context/ files before compacting"},{"name":"Compact Decision","description":"Compact now, continue until natural break, or restructure the approach"}] |
Token Budget Skill
Manage context window spend in long sessions. Prevents the silent failure mode where context fills up mid-task and Claude starts dropping earlier instructions.
What Claude Gets Wrong Without This Skill
Without active budget management, context fills gradually and silently. Claude begins deprioritizing early rules, earlier decisions, and the beginning of the task plan. The first thing to be dropped is often the most important — the constraints and goals stated at session start.
The failure mode is not an error. It is drift that is invisible until the work is noticeably wrong.
Context Window Spend Estimation
Claude cannot precisely count tokens mid-conversation. Use these rough signals:
Low usage (safe):
- Conversation just started
- Only a few files have been read
- No large code blocks or file contents in context
Medium usage (watch):
- Multiple large files have been read and quoted
- Long code generation has happened
- Several agent spawns have returned results
- The session has been running for 30+ minutes of active work
High usage (act soon):
- Earlier parts of the conversation are likely compressed
- Recall of details from early in the session is uncertain
- The system prompt rules feel less "active"
- You are getting suggestions that contradict early decisions
Critical (act now):
- You cannot recall a constraint from early in the session
- The heartbeat brief from session start is gone
- Rules from CLAUDE.md are not being applied
Compaction Thresholds (from Claude Code source)
Claude Code's autocompact triggers at 93% of effective context where:
effectiveWindow = contextWindow - 20,000 (reserved for compaction overhead)
PSC acts earlier:
| Threshold | State | Action |
|---|
| ~90% | Warning | Run /checkpoint immediately |
| ~93% | Autocompact trigger | Claude Code may compact without warning |
| ~95% | Blocking | New tool calls may be refused |
Time-based trigger: If a session has been running for more than 2 hours of active work without compaction, consider compacting at the next natural task boundary — regardless of estimated token count. Long sessions accumulate drift that is invisible in usage estimates.
Cache-efficiency signal: If Claude is repeating itself or reconstructing reasoning it has already done, the cached context may no longer be serving it. This is a secondary compaction signal independent of token count.
Pre-Compact Capture Protocol
Before compacting, write to context files anything that is not already there:
- Open decisions — any decision made this session that is not yet in
context/decisions.md
- Active constraints — constraints discovered this session not in
context/project.md
- In-progress state — current task, which step, what is done, what is next
- Blocking learnings — anything discovered that would change the approach
Format for in-progress state:
## In-Progress State — [date]
Task: [what is being worked on]
Status: Step [N] of [N] — [current step name]
Completed: [list]
Next: [specific next action]
Blocker: [if any]
Write this to context/learnings.md under a state category entry.
Compact Decision Matrix
| Situation | Decision |
|---|
| At a natural task boundary | Compact now — clean state |
| Mid-task, state can be fully captured | Pre-compact capture, then compact |
| Mid-task, complex state hard to capture | Continue to next natural break |
| Actively debugging with rich accumulated context | Do not compact — the context IS the tool |
| Early in session, usage is low | Continue — no action needed |
After Compacting
Run heartbeat immediately. The session brief re-establishes context. Read context/learnings.md for the in-progress state entry if one was written.
Anti-Patterns
Do not compact mid-implementation without writing state first. Coming back to an empty context after compaction means re-reading everything.
Do not compact during an active debug session. The accumulated evidence is the most valuable part.
Do not ignore high-usage signals. Drift is silent and cumulative.
Mandatory Checklist
- Verify open decisions were written to context/decisions.md before compacting
- Verify in-progress state was written to context/learnings.md before compacting
- Verify compact decision was based on usage assessment, not just "it's been a while"
- Verify heartbeat was run immediately after compacting
