Context usage percentage only counts input tokens, causing misleading 'Context limit reached' at ~20%

Resolved 💬 4 comments Opened Feb 24, 2026 by neuer Closed Apr 29, 2026

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

  1. Start a Claude Code session with a 1M context model (e.g., claude-opus-4-6[1m])
  2. Have a conversation that generates substantial output (long code responses, large tool outputs, file reads, etc.)
  3. Eventually receive the message: Context limit reached · /compact or /clear to continue
  4. Run /context to 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:

  1. context_window.used_percentage field (used by status line scripts)
  2. /context command 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)

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗