Claude Code /compact

The command that summarizes your conversation to extend your session — and why knowing your usage % before running it matters.

When to run /compact

The right time is before the context window fills up, not after it forces a compaction. Watch for these signals:

• Context % above 70% — Headroom shows contextUsagePct as the third number in v0.3.5 (CC 23%·41%·74%). Amber at this point means a natural compaction soon.
• Session % climbing fast — If your session % is rising quickly, the context is large and each request is expensive. Compact early to slow the burn.
• Before a long task — If you're about to start a 45-minute refactor and you're at 40% session, compact first to maximize your headroom for the task.

The /compact + session limit relationship

Each Claude Code request burns a fixed cost for your prompt (your question) plus a variable cost for the context (the conversation so far). A long context means every request is expensive, even short ones.

After /compact:

• The context window drops significantly (fewer tokens in the summary vs. the full history)
• Each subsequent request is cheaper (smaller context prefix)
• The session % rises slower — the same work now fits more into the session window

Check your context % from the command line

# See all three usage meters at once
jq '{sessionUsagePct, weeklyUsagePct, contextUsagePct}' ~/.claude/headroom-usage.json

The contextUsagePct field shows how full the current context window is (0–100%). When this is high, each request burns more from the session budget. When it's low (after /compact), requests are cheaper.

The compact workflow

# 1. Check where you are before compacting
jq '{session: .sessionUsagePct, context: .contextUsagePct}' ~/.claude/headroom-usage.json

# 2. Run /compact in Claude Code (type it in the Claude Code prompt)
/compact

# 3. Verify the context % dropped
jq '.contextUsagePct' ~/.claude/headroom-usage.json

What /compact loses and keeps

After compaction, Claude has a summary of what happened — it knows what files were touched, what decisions were made, what the current task is. It doesn't have the exact wording of every turn.

This is fine for most work. Where it matters: if you were in the middle of debugging a subtle issue and relied on Claude remembering an exact error message or stack trace, the summary might not capture that detail. In those cases, compact at a logical break point (task done, file saved, test passing) rather than mid-investigation.

Auto-compact

Claude Code can be set to compact automatically when the context approaches a threshold. Check your Claude Code settings for the auto-compact option. Whether you use auto or manual, the key is that you don't hit the hard limit mid-task — either approach works; manual gives you more control over timing.

Headroom shows all three meters

Headroom's menu bar item shows session % and weekly %. Version 0.3.5 adds the context % as a third number. The dropdown shows all three with reset countdowns.

brew install --cask patwalls/tap/headroom

Or download directly. Free, MIT, ~267 KB.

→ 5-hour session limit guide
→ Context window % explained
→ Full rate limits guide