Context percentage ~2-3% lower than /context command

[jarrodwatts]

Summary

The HUD's context percentage displays ~2-3% lower than Claude Code's /context command.

Example:

• /context shows: 88k/200k tokens (44%)
• claude-hud shows: 41%

Investigation Findings

Added debug logging to getContextPercent() to capture stdin values. Key findings:

stdin reports fewer tokens than /context

When claude-hud showed 39%, stdin reported:

input:10 cache_create:33214 cache_read:0 total:33224
calc: (33224 + 45000) / 200000 = 39%

But /context showed 82k tokens used (41%) at the same time.

The gap: stdin reports ~33k, /context counts ~82k = ~49k token difference

The AUTOCOMPACT_BUFFER compensation

The current formula adds a 45k buffer to compensate:

return Math.min(100, Math.round(((totalTokens + AUTOCOMPACT_BUFFER) / size) * 100));

This gets us closer but not exact. The ~49k gap suggests the buffer should be slightly higher, or the approach has inherent limitations.

What stdin appears to be missing

The stdin current_usage from Claude Code provides API-level token counts:

• input_tokens - uncached prompt tokens
• cache_creation_input_tokens - newly cached tokens
• cache_read_input_tokens - tokens read from cache

The /context command internally counts:

• System prompt (~2.9k)
• System tools (~20k)
• MCP tools (~4.9k)
• Custom agents (~2.2k)
• Memory files (~5.4k)
• Messages (variable)

The API usage response may not include all categories that /context counts, or counts them differently (billable vs context window tokens).

Potential Solutions

1. Increase buffer - Bump AUTOCOMPACT_BUFFER from 45k to ~49-50k for better approximation
2. Dynamic calculation - Parse transcript JSONL to count tokens similar to how /context does
3. Accept variance - Document the ~2-3% difference as expected behavior given the different data sources
4. Request upstream - Ask Claude Code team to expose the same token breakdown in stdin data

Debug Data

Sample stdin values captured:

2026-01-04T12:20:35 | input:7 cache_create:459 cache_read:49458 total:49924 calc:47%
2026-01-04T12:21:25 | input:10 cache_create:33214 cache_read:0 total:33224 calc:39%
2026-01-04T12:26:48 | input:7 cache_create:12618 cache_read:69984 total:82609 calc:64%

Note: cache_read:0 correlates with lower totals (cache miss/invalidation scenarios).

[unlux]

something similar
autocompact is disabled btw.
so is an upstream thing too.

[zataara]

I'm also showing a mismatch in context values. HUD is showing 32% when /context is showing 9%.

[jarrodwatts]

Fixed in #55! The HUD now has a display.autocompactBuffer config option:

• 'enabled' (default): Shows buffered % (matches /context when autocompact ON)
• 'disabled': Shows raw % (matches /context when autocompact OFF)

If you have autocompact disabled, set autocompactBuffer: 'disabled' in your config to see raw percentages.