fix: context percent now matches /context output exactly

[r-firpo]

---

TL;DR

The HUD's context percentage was showing significantly inflated values compared to Claude Code's /context command. because it was assuming all users would have the auto-compaction feature enabled, however I don't use CC auto-compaction because i think its too noisy. Because I compact ad-hoc (usually very near the limits of the context winxow) compaction the HUD might show 88% while /context reports 65%. This caused confusion about actual context usage. The fix separates "display percentage" (raw, matches /context) from "warning percentage" (buffered, used for color thresholds and compact warnings).

Problem

When Claude Code compacts a conversation, the actual token count drops significantly—but the HUD was adding a hardcoded 45,000 token "autocompact buffer" to the percentage calculation. This buffer exists because Claude Code triggers autocompact around 45k tokens before hitting the limit, so the buffer helps warn users before that happens. This buffer was being applied to the displayed percentage, not just the warning thresholds.

However, the actual auto-compaction thresholds i don't think are reported (i assume this plugin tried to reverse engineer it), nor are they guaranteed to be deterministic (tracking them with a constant is flaky) and very well could be changed often, and model dependent. The result:

• Misleading display: User sees 88% in HUD but /context shows 65%
• Post-compaction confusion: After compacting, the HUD still shows high usage even though actual usage dropped
• Trust erosion: Users learn not to trust the HUD's percentage, defeating its purpose! (I had to constantly check the /context even when using the plugin)

The core issue was conflating two different concepts:

1. Actual context usage - what /context reports, what the user cares about
2. Compact risk level - when to start warning about approaching autocompact

Solution

This PR proposes we calculate and use two separate percentages:

getContextPercent(stdin) - Raw percentage (for display)

// Returns actual token usage / context window size
// This matches what /context reports
const percent = getContextPercent(ctx.stdin); // e.g., 65%

getBufferedPercent(stdin) - Buffered percentage (for warnings)

// Returns (actual tokens + 45k buffer) / context window size
// This represents "compact risk" level
const bufferedPercent = getBufferedPercent(ctx.stdin); // e.g., 88%

How they're used together

Element	Uses	Why
Displayed percentage	Raw	Users see actual usage matching /context
Progress bar color	Buffered	Warns early about approaching autocompact
Token breakdown (85%+)	Buffered threshold	Shows details when compact risk is high
"COMPACT" warning	Buffered	Appears at 95% compact risk, not 95% actual
"X% until auto-compact"	Buffered	Shows remaining headroom before autocompact triggers

Example output at 65% actual / 88% buffered:

[Opus] ██████░░░░ 65% | my-project (in: 130k, cache: 5k) (12% until auto-compact if enabled)

• Shows 65% (actual usage, matches /context)
• Bar is yellow (buffered 88% > 70% warning threshold)
• Token breakdown shown (buffered 88% > 85% detail threshold)
• Shows 12% remaining until autocompact would trigger (100% - 88%)
• Compact threshold warning goes away after theoretically threshold is reached

Files Changed

• src/constants.ts - Added documentation explaining the AUTOCOMPACT_BUFFER constant
• src/stdin.ts - Added getBufferedPercent() function alongside existing getContextPercent()
• src/render/session-line.ts - Updated to use raw percent for display, buffered percent for thresholds
• tests/core.test.js - Added tests for both percentage functions including regression test
• tests/render.test.js - Added test verifying the autocompact indicator appears correctly
• CHANGELOG.md - Documented the fix

Screenshots
BEFORE

This was the output of /context after a compaction

And this is what claude-hud would say

AFTER
This accurately reflects the actual context 1:1 and shows a friendly hit for those who have auto-compaction turned on

---

[r-firpo]

@jarrodwatts Think i found the source of at least some of the context-management discrepancies people have been reporting. The plugin was using a fix buffer for the "auto compaction" threshold (ie. how much context you have left until claude auto-compacts) and adding it to your context heuristically, treating it as a fixed amount of context to always add to usage. But a) if you dont use auto-compact (i dont) this doesn't work; b) It's not technically accurate. I think auto-compaction threshold should probably be a best-effort warning rather than a fixed addition to your used context. The users context is strictly just the amount of token's they've used

[jarrodwatts]

Thank you for your contribution! Your dual-percentage approach (raw display + buffered warnings) was incorporated into #55, which adds a configurable toggle and percentage-based buffer scaling.

Credit: Your ideas from this PR informed the final solution. 🙏