Context Compact

Purpose

Prevent context bloat using reported usage when exposed or concrete working-set pressure when not, and adapt reading and delegation behavior before it becomes a problem. When fill gets high, compact what you can and tell the user to run /compact (or /clear when the task is done).

When to use

Trigger automatically when any of these holds:

• The conversation is long (10+ turns) or the user mentions "context", "compact", "/compact", "token"/"token usage", "context size", "heavy/cluttered/long context", or asks to "keep it light" — in any language the user speaks.
• About to read a file you suspect is large (> 300 lines) or whose size you don't know yet.
• Right after reading a large file while the task continues.
• The user mentions token usage, cost, or session speed.
• Exploration is complete and implementation is about to start, when actual pressure makes that a useful safe handoff point (see Rules).

Do not trigger for trivial single-file lookups on a fresh session.

Preconditions

• Use client-reported usage/window size when available. If neither is exposed, context usage is unknown; do not manufacture token counts or fill percentages.

Workflow

1. Check the budget signal. Use the active client's reported context window and usage, if available. Never assume every model supports 600K/1M or that file byte counts measure the active context.
2. Assess working-set pressure. If reported usage is unavailable, inspect practical signals: repeated large reads, losing relevant state, or unreliable recall. Keep usage labeled unknown; use targeted reads without inventing a percentage.
3. Compare → mode using the table in Rules.
4. Adapt per mode. Change how you read and delegate before doing anything else.
5. Compact when heavy (fill > 70% — or the absolute cap in step 6). Re-express what you still need as short notes; stop holding full file contents in context; explicitly recommend /compact to the user (and /clear when the task is done).
6. Optional absolute cap. When client-reported context exceeds 500K tokens and that cap is relevant to the actual model, recommend /compact immediately — regardless of percentage bands. The goal is cutting token cost, so trigger early, not at the window edge.
7. Sensitive-work exception. Do NOT recommend compaction during data-loss-risk, security, irreversible-operations, or state-heavy debugging work — losing detail can change the outcome. Keep full context and state the tradeoff explicitly.
8. Preserve thread and plan. Immediately before recommending /compact//clear, write a 2–4 line handoff note (current task • plan • decisions • next steps) so the summary retains the thread.
9. Report only meaningful pressure. Explain a needed handoff or compaction briefly; do not emit a usage estimate on every routine read. If no usage metric is exposed, say it is unknown when asked.

Rules

• The numeric bands above apply only to reported usage against a known window. Character/byte estimates are not reliable context measurements, especially for multilingual content.
• A full Read adds the file to the current working context — prefer Read with offset/limit, or grep, when a section suffices.
• Multi-file search is normally a targeted local search. Delegate only when independent scopes, available tools and authorization make it useful; do not require a subagent merely because a search touches multiple files.
• When you summarize/drop a file, never later quote its exact code as if it is still loaded — re-read only the needed lines.
• At reported high pressure, avoid unnecessary large reads but retain enough context to understand every edit.
• Plan boundary: approval alone does not trigger compaction. Use a completed exploration/plan as a safe handoff point only when actual context pressure justifies it, respecting the sensitive-work exception.

Compact handoff (delivering /compact)

The agent never runs /compact itself — the user does. Deliver it exactly like a privileged command (the sudo-handoff pattern):

1. State the observed trigger. Cite reported usage if available, otherwise describe concrete working-set pressure without invented counts.
2. Prepare the handoff note (2–4 lines: current task • plan • decisions • next steps), retaining the important constraints.
3. Give the supported copy-pasteable command in a fenced block, then put the handoff note after it as the last content:

   /compact

   Preceded by one sentence of what it does and why it's needed.
4. Continue bounded useful work unless a pause is required. Recommend the command only if the client supports it. Do not block an authorized task merely because a recommendation was made; never claim compaction ran without confirmation.
5. Resume from the note once the user confirms. Never assume it ran.

Rules:

• The note must be the last thing you write — the summary keeps the tail of the conversation.
• Never deliver a handoff during sensitive work (see Workflow step 7).
• If the user declines, keep working in constrained mode — don't nag repeatedly.

Common mistakes

• Counting only the last message — context is cumulative since the session started.
• Reading a whole file when grep + offset/limit would do (the biggest waste by far).
• Silently continuing after heavy reads instead of recommending /compact — the user can't see your token usage.
• Summarizing a file but then still referencing its exact contents (it's gone — you must re-read).
• Treating this skill as optional because "the AGENTS.md already has context rules" — this is the procedure for those rules; the rules are the thresholds, this is the loop.
• Recommending /compact during sensitive work (data-loss risk, security, irreversible ops, state-heavy debugging) just to save tokens.
• Crossing 500K tokens without telling the user that every further read is expensive — a missed compaction makes each re-read costlier than the compaction itself.

Validation

• Any stated usage/band traces to client-reported metrics; unknown metrics stay unknown. Targeted reads preserve necessary edit context.
• After compacting, the session should feel lighter: the next user turn should show a smaller working set (fewer large reads).
• When the client reports high pressure, a supported compaction recommendation occurs at a safe boundary; lack of an unavailable metric is not a skill failure.
• If reported usage crossed an applicable cap, note whether supported compaction was recommended or deferred for safety; do not assert an unmeasured threshold was crossed.
• A handoff note exists right before every /compact//clear recommendation, so the thread and plan survived the summary.
• The user confirms /compact ran, and you resume from the pre-written note rather than from memory.