[FEATURE] Allow Claude to access its token usage

Problem

Claude Code tracks token usage internally, but Claude (the AI) has no way to access this information. When a user asks:

• "How many tokens have we used?" - Claude cannot answer
• "How much context is left?" - Claude cannot answer
• "What has this session cost?" - Claude cannot answer

The information exists in Claude Code but isn't exposed to Claude's context.

Current State

| Context | Has token usage? |
|---------|------------------|
| Statusline (JSON input) | ✅ (via transcript parsing) |
| Hooks (JSON input) | ❌ |
| Bash commands | ❌ |
| Claude AI context | ❌ |

Use Cases

• Proactive context management: Claude could warn users before hitting context limits instead of abruptly stopping
• Cost awareness: Users could ask Claude to estimate session cost or daily spend
• Workflow decisions: "Do we have enough context left to complete this refactoring task?"
• Transparency: Users understanding what they're consuming in real-time

Proposed Solutions

Option A: Environment variables

export CLAUDE_TOKENS_USED=45000
export CLAUDE_TOKENS_TOTAL=200000
export CLAUDE_CONTEXT_PERCENT=22

Option B: Injected system context
Claude's context could include current usage stats, updated periodically.

Option C: Tool/command
A read-only tool Claude can invoke to check usage, like /status but programmatically accessible.

Note

I understand there may be business considerations around exposing detailed usage data. Even approximate or read-only visibility would be valuable for the use cases above.

Related Issues

• #10436 - Token usage in statusline (completed, but only for statusline display - not Claude's context)
• #8861 - Token usage in status line API (closed)
• #10593 - Real-time token usage indicator in CLI