[FEATURE] Show estimated token count before sending prompt

Feature Request

Integrate the Token Counting API (POST /v1/messages/count_tokens) into Claude Code CLI to display estimated input token count before the message is sent to the model.

Motivation

Currently, users have no visibility into how many tokens a prompt will consume until after it's sent. This makes it difficult to:

• Manage costs proactively — users can't decide whether to simplify a prompt before incurring charges
• Avoid context window limits — large prompts with images, PDFs, or long conversations may silently hit limits
• Understand token composition — system prompt, tools, conversation history, and user input all contribute to input tokens, but their individual impact is opaque

The Token Counting API is free to call and returns results quickly, making it ideal for a pre-send preview.

Proposed Behavior

Show estimated token count in the input area (e.g., status line or below the prompt) as the user composes their message:

> Explain this codebase architecture...
                                          ~2,345 input tokens | session: 45,678

Implementation options (any would be valuable):

1. Real-time estimate — debounced call to /v1/messages/count_tokens as the user types, displayed in the status line
2. On-submit preview — count tokens on Enter, briefly show the count before sending (with optional confirmation if above a threshold)
3. Config-driven — a setting like "showTokenEstimate": true or --show-token-estimate flag

Key considerations:

• The count should include the full payload: system prompt + tools + conversation history + current input (not just the current message text)
• The Token Counting API is free and supports all message formats (text, images, PDFs, tools)
• A debounced approach (e.g., 500ms after typing stops) would minimize unnecessary API calls

Why Hooks Can't Solve This

I investigated using UserPromptSubmit hooks as a workaround, but:

• Hooks don't have access to the full conversation context (history, system prompt, tools)
• Hook output is injected as context for Claude, not displayed as UI to the user
• UserPromptSubmit cannot block sending to allow user decision-making based on the count

This needs to be a native CLI feature.

Related

• #29600 — requests per-request token counts after response (complementary, not overlapping)
• Anthropic docs: Token Counting