Token Usage Summary that Claude Code can read to adjust its own work tasks

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

The Claude API returns token usage metadata (input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens) in every response. This data is available to the Claude Code client but is never fed back to the model within the conversation.

This means the model cannot accurately track its own context window consumption. In practice, it relies on rough heuristic estimation (e.g., "I've loaded a lot of files, so I'm probably at ~60%"), which consistently underestimates actual usage. Users who care about context management end up manually tracking token counts from the UI and prompting the model to wrap up — a workflow that works but shouldn't
require human bookkeeping.

Proposed Solution

Inject a lightweight token usage summary into the conversation context, either:

1. System message after each turn — e.g., [Context: 142,387 / 200,000 tokens used (71.2%)]
2. A read-only tool the model can call — e.g., get_context_usage() returning {input_tokens_total, output_tokens_total, context_window_size, percent_used}
3. Periodic system reminder — injected at configurable thresholds (e.g., 50%, 75%, 90%)

Any of these would close the observability gap.

Alternative Solutions

Use Case

Long-running agentic sessions that manage context budgets — particularly sessions with structured wrap/handoff protocols that need to start cleanup at specific context thresholds. Currently the user must watch token counters in the UI and manually signal the model. With this feature, the model could self-manage its pacing and wrap timing.

Opt-in

This could be a setting (e.g., "exposeTokenUsage": true in .claude/settings.json) for users who want context-aware model behavior. Users who don't care about context management wouldn't see any difference.

Priority

Medium - Would be very helpful

Feature Category

File operations

Use Case Example

Long-running agentic sessions that manage context budgets — particularly sessions with structured wrap/handoff protocols that need to start cleanup at specific context thresholds. Currently the user must watch token counters in the UI and manually signal the model. With this feature, the model could self-manage its pacing and wrap timing.

Additional Context

Observed empirically across 230+ development sessions: the model's heuristic context estimates consistently undershoot by ~35% compared to actual token counts visible in the Claude Code UI. The user's manual tracking (summing KB displayed per thinking block) is more accurate than the model's self-assessment — which is the opposite of how it should work.