[DOCS] Fix inaccurate context window calculation logic in status line configuration examples

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/statusline

Section/Topic

The Context Window Usage section, specifically the "Advanced approach with manual calculation" code example.

Current Documentation

The current example script for the advanced approach uses the following logic to calculate the percentage used:

# Calculate current context from current_usage fields
CURRENT_TOKENS=$(echo "$USAGE" | jq '.input_tokens + .cache_creation_input_tokens + .cache_read_input_tokens')
PERCENT_USED=$((CURRENT_TOKENS * 100 / CONTEXT_SIZE))
echo "[$MODEL] Context: ${PERCENT_USED}%"

It divides the current token count strictly by the total context_window_size.

What's Wrong or Missing?

The manual calculation logic (CURRENT_TOKENS * 100 / CONTEXT_SIZE) is misleading because it does not account for the effective context window.

Claude Code reserves a specific amount of space for output tokens/thinking tokens. As noted in recent changelogs (v2.1.7), the blocking limit and auto-compaction triggers are calculated based on the effective context window (Total - Reserved), not the raw total.

Users relying on the current example script will calculate a usage percentage that suggests they have more space than they actually do. This will lead to unexpected auto-compaction or blocking behaviors occurring before their status line indicates the context is full.

Suggested Improvement

The documentation should be updated to recommend using the pre-calculated used_percentage field provided in the JSON input, as this field already handles the effective limit logic correctly internally.

If the "Advanced approach" example is retained to show how to parse specific fields, it should include a warning that the manual formula is an approximation that ignores the output token reservation buffer.

Preferred fix: Update the example to prioritize the used_percentage field even in the advanced script, or update the formula to conceptually represent: CURRENT_TOKENS / (CONTEXT_SIZE - RESERVED_TOKENS).

Impact

High - Prevents users from using a feature

Additional Context

• Context: This relates to changes in how Claude Code handles effective context windows versus full context windows.
• Reference: The JSON input structure in the documentation already shows used_percentage is available: used_percentage: 42.5. Using this upstream value is more robust than asking users to maintain their own calculation logic in bash.