Context window warning doesn't fire: meter tracks conversation tokens only, not actual API usage

Resolved 💬 3 comments Opened Mar 3, 2026 by JohnGalt017 Closed Mar 3, 2026

Bug Report

Summary

The built-in context window warning never fires because the context meter only counts conversation tokens, excluding system prompts, rules, and tool definitions that Claude Code silently adds to every API request. This causes a misleading percentage that doesn't reflect actual API usage — and the warning threshold is keyed to this wrong metric.

What happened

Status bar showed 117k/200k (58%) — no warning appeared. The very next response hit:

API Error: The model has reached its context window limit.

Root cause

Every API request includes hidden overhead that the meter doesn't count:

| Component | Approx tokens |
|-----------|--------------|
| Conversation (what meter shows) | 117k |
| System prompt | ~5k |
| CLAUDE.md | ~3k |
| Rules files (rules/*.md) | ~15k |
| Skill definitions | ~10k |
| Tool definitions | ~5k |
| Actual API request | ~155k |

The meter showed 58% but actual API usage was ~77%+.

Bug chain

Actual API usage:        ~155k/200k (~77%)
                              ↓
Meter shows:              117k/200k (58%)
                              ↓
Warning threshold:        ~80% = 160k (based on meter)
                              ↓
Warning never fires  ←  because 117k < 160k
                              ↓
Next response → overflow → hard error (no warning)

Expected behavior

  • Context meter should reflect total tokens sent to API (conversation + system overhead)
  • Built-in warning should fire based on actual API usage, not just conversation tokens
  • Or at minimum: warning should account for known system overhead when calculating threshold

Environment

  • Model: claude-opus-4-6
  • Context at time of error: 117k/200k shown (58%)
  • Platform: macOS

View original on GitHub ↗

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