Runtime Token Usage Visibility for Claude Code

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

Summary

Provide Claude Code with runtime access to token consumption metrics, enabling AI-assisted budget management and self-regulation during sessions.

Current Problem

Claude Code has no visibility into:

• Tokens consumed in current session
• Remaining budget/quota
• Cost per operation
• Session token trajectory

This prevents implementation of:

• Automatic efficiency optimization
• Budget-aware decision making
• Session cost estimation
• Self-imposed limits when approaching thresholds

Proposed Solution

Proposed Solution

Expose token metrics via environment variable or internal API:

CLAUDE_SESSION_TOKENS_USED=45000
CLAUDE_SESSION_TOKENS_REMAINING=55000
CLAUDE_SESSION_BUDGET=100000
CLAUDE_COST_PER_1K_INPUT=0.003
CLAUDE_COST_PER_1K_OUTPUT=0.015

Or provide a system function:

get_token_usage() -> {used: int, remaining: int, budget: int}

Use Cases

1. Budget Alerts: Claude warns user when approaching limits
2. Efficiency Mode: Auto-switch to concise responses near budget
3. Cost Reporting: Provide session cost summary

4.Task Prioritization: Skip low-value operations when budget tight

1. User Control: Allow users to set soft limits Claude respects

Benefits

• Increased user trust through transparency
• Reduced unexpected billing
• Enables power users to define efficiency strategies
• Supports enterprise budget compliance
• Aligns AI behavior with user resource constraints

Implementation Suggestion

Read-only access is sufficient. Claude doesn't need to modify budgets, only observe current state to make informed decisions.

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

_No response_

Additional Context

_No response_