Expose context window usage metrics to Claude for self-analysis

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

There is currently no way for Claude to inspect its own context window consumption during a session. Context usage is
effectively profiling data for Claude Code — without access to it, Claude cannot identify inefficiencies, make
informed decisions about tool strategies, or proactively manage context pressure.

What I'd like to see:

• A tool or introspectable API that gives Claude itself access to context usage metrics during a session
• Per-turn breakdown of context consumption (user messages, tool calls, tool results, system prompts, cached vs.

uncached tokens)

• Running total of context used vs. remaining capacity
• Identification of the largest context consumers in the current session (e.g., which tool call returned the most

tokens, how much context CLAUDE.md files and system prompts consume)

Why this matters:

• Context is a finite, expensive resource that directly impacts session cost, performance, and when conversation

compression kicks in

• If Claude could see its own context usage, it could adapt its behavior — choosing to spawn subagents for isolation,

trimming verbose tool calls, or warning the user before compression

• Analogous to a profiler for code execution — Claude needs this data to optimize its own operations
• Power users managing complex multi-agent sessions would benefit from Claude reasoning about context tradeoffs (e.g.,

"this file read will consume 15% of remaining context — spawning a subagent instead")

• Currently, both Claude and the user are flying blind

Proposed Solution

Claude should be able to use an API call to get the current total usage with a breakdown similar to what a user sees when using the /context command. In addition, there should be a way post tool use to collect the token usage, either by hook or a direct API interface that Claude is aware of. Here's an example of what I'm thinking below:

Architecture:

PostToolUse hook fires
→ receives token usage in env/stdin (needs to be exposed)
→ appends to a local log file
→ checks thresholds
→ only injects a stdout message when actionable

The hook script (runs after every tool call, costs zero context tokens):

#!/bin/bash

.claude/hooks/context-monitor.sh

LOG="$SESSION_DIR/context_usage.jsonl"

Append per-tool-call metrics to log (zero context cost)

echo "{\"turn\":$TURN,\"tool\":\"$TOOL_NAME\",\"input_tokens\":$INPUT_TOKENS,\"context_used\":$CONTEXT_USED,\"context_
total\":$CONTEXT_TOTAL,\"timestamp\":\"$(date -Iseconds)\"}" >> "$LOG"

Only inject into context when threshold crossed

PERCENT=$((CONTEXT_USED * 100 / CONTEXT_TOTAL))
PREV_PERCENT=$(cat "$SESSION_DIR/.last_threshold" 2>/dev/null || echo 0)

if [ "$PERCENT" -ge 75 ] && [ "$PREV_PERCENT" -lt 75 ]; then
echo 75 > "$SESSION_DIR/.last_threshold"
echo "Context at 75% — consider checkpointing or spawning subagents for large operations."
elif [ "$PERCENT" -ge 90 ] && [ "$PREV_PERCENT" -lt 90 ]; then
echo 90 > "$SESSION_DIR/.last_threshold"
echo "Context at 90% — compaction imminent. Save critical state now."
fi

When Claude wants to profile, it reads the log file — one tool call, on demand:

{"turn":1,"tool":"Read","input_tokens":2100,"context_used":18000,"context_total":200000,"timestamp":"..."}
{"turn":2,"tool":"Bash","input_tokens":450,"context_used":19200,"context_total":200000,"timestamp":"..."}
{"turn":3,"tool":"Read","input_tokens":12800,"context_used":32000,"context_total":200000,"timestamp":"..."}

What this gets you:

• Collection cost: zero tokens. Hook runs out-of-band, writes to disk.
• Ambient awareness cost: near-zero. Stdout injection only on threshold crossings — maybe 2-3 times per session.
• Profiling cost: one Read call. Only when Claude or the user wants to analyze.
• Full history preserved. JSONL log survives compaction — Claude can read profiling data from before compaction

happened, which is exactly when you'd want it most.

What's missing today to make this work:

The hook system doesn't currently expose token/context data in the hook environment. Issues #34340 and #29829 are
requesting exactly that — expose CONTEXT_USED, INPUT_TOKENS, etc. as environment variables or in the hook's stdin
payload. That's the prerequisite. Once hooks have the data, everything else is userland.

The reason I'm providing this even though there are others is the specific use case and explanation.

The feature request boils down to: expose token usage metadata in hook event data. The rest can be built by users.

Alternative Solutions

I tried having Claude read the output conversation which has some token usage in there, but doing so was extremely token use intensive so that was scratched as a plan.

Priority

Critical - Blocking my work

Feature Category

Performance and speed

Use Case Example

I'm building an entire architecture to make Claude more effective with user in the loop flow. The goal is to create an agent team that works semi autonomously and takes in user input as it works through a plan. The issue I'm running into frequently is that the architecture is complicated, I want Claude to have self reinforcing loops and doing things more intelligently as it builds. The downside is some tasks can be incredibly inefficient (context wise) and completely bloat the project. I have no good way to track this information and optimize my flow. There's no reason for this, understanding how to profile the tools would be helpful so we can make them more efficient. Using "/context" gives us some insight, but per tool usage is completely not part of that. I need to be able to understand things better.

One example is I was trying to do exactly this, collect context use. What Claude decided was a way to interpret that was to read the entire message history and find where it noted token usage. First, there's a lot of information missing from that, second, there's a ton of assumptions in there. And third, it was reading an insane amount of text and bloating itself like crazy with unnecessary context. Exactly what I was trying to track down as an issue. When I noticed this through manual checking I was able to remove this feature. The fact that I have no way to test against this in any systemic way is quite silly.

The architecture uses a self reinforcement loop with the tools granted outside of retraining the LLM itself. Without safeguards like watching for excessive context use and bloat, I cannot maintain things effectively. Additionally with the new, greater context limits, the Claud.md gets ignored over time. I could get an idea when this degradation happens via testing, but I have no way to test what amount of context usage causes the attention loss over time since I can't check this. What other paths do I have?

Additional Context

_No response_