Context usage percentage only counts input tokens, causing misleading 'Context limit reached' at ~20%
Bug Description
The context usage percentage displayed in both the status line (used_percentage) and the /context command only accounts for input tokens, while the actual context limit check considers total tokens (input + output + cache). This creates a confusing situation where users see low usage but hit the context limit.
Steps to Reproduce
- Start a Claude Code session with a 1M context model (e.g.,
claude-opus-4-6[1m]) - Have a conversation that generates substantial output (long code responses, large tool outputs, file reads, etc.)
- Eventually receive the message:
Context limit reached · /compact or /clear to continue - Run
/contextto check usage
Actual Behavior
/context output shows ~20% usage while the "Context limit reached" message has already been triggered:
Context Usage
199k/1000k tokens (20%)
Estimated usage by category
System prompt: 1.1k tokens (0.1%)
Skills: 833 tokens (0.1%)
Free space: 965k (96.5%)
Autocompact buffer: 33k tokens (3.3%)
The status line also showed ~20% before the limit was hit.
Expected Behavior
The displayed percentage should reflect total context window consumption (input + output + cache tokens), not just input tokens. This way, users can anticipate when they're approaching the limit and take action proactively.
Root Cause Analysis
used_percentage is calculated as:
(input_tokens + cache_creation_input_tokens + cache_read_input_tokens) / context_window_size * 100
Output tokens are excluded from this calculation, but they DO consume context window space and ARE considered when triggering the "Context limit reached" check.
Suggested Fix
Include output tokens in the percentage calculation:
(input_tokens + output_tokens + cache_creation_input_tokens + cache_read_input_tokens) / context_window_size * 100
This should be applied to:
context_window.used_percentagefield (used by status line scripts)/contextcommand display
Workaround
Users can work around this by writing a custom status line script that manually calculates total usage from the individual token fields:
used=$(echo "$input" | jq -r '
.context_window |
if .context_window_size and .context_window_size > 0 then
(((.input_tokens // 0) + (.output_tokens // 0)
+ (.cache_creation_input_tokens // 0)
+ (.cache_read_input_tokens // 0))
/ .context_window_size * 100 * 10 | floor / 10 | tostring)
else
.used_percentage // empty
end
')
Environment
- Claude Code version: 2.1.52
- Model: claude-opus-4-6[1m] (1M context)
- OS: macOS (Darwin 25.2.0)
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗