Problem Statement

When customizing the status line using the status line configuration feature, users cannot access detailed token usage information (input tokens, output tokens, cache read tokens, cache creation tokens). The current status line API only provides aggregate cost information (total_cost_usd) but not the underlying token metrics that contribute to that cost.

This limits visibility into:

• How tokens are being distributed across input/output
• Cache hit rates and efficiency
• Detailed cost breakdowns for budgeting and optimization

Users who want to monitor their token usage in real-time (especially those on budget constraints or analyzing performance) need to run the /cost command separately, which interrupts their workflow.

Proposed Solution

Add token usage fields to the status line JSON API, similar to the existing cost object structure. The enhanced API could look like:

{
  "cost": {
    "total_cost_usd": 0.123,
    "total_duration_ms": 45000,
    "total_api_duration_ms": 12000,
    "total_lines_added": 150,
    "total_lines_removed": 45,
    "total_input_tokens": 25000,
    "total_output_tokens": 8000,
    "total_cache_read_tokens": 15000,
    "total_cache_creation_tokens": 5000
  }
}

This would allow users to display token metrics in their custom status lines, for example:

echo "Tokens: ⬇️ $input_tokens | ⬆️ $output_tokens | 💾 $cache_tokens"

Alternative Solutions

1. Currently, users must run /cost or /usage commands to see token details, which is not integrated into the status line workflow
2. Some users might parse transcript files or logs to extract token information, but this is inefficient and not real-time
3. Other CLI tools with AI integrations often expose token metrics in their status displays

Priority

Medium - Would be very helpful

This feature would significantly improve visibility and allow users to make informed decisions about their usage patterns, especially useful for:

• Monitoring budget constraints
• Optimizing prompts for token efficiency
• Understanding cache effectiveness

Feature Category

Configuration and settings

Use Case Example

Example scenario:

1. A developer is working on a large codebase and has configured a custom status line
2. They want to keep an eye on token usage to stay within budget limits
3. With this feature, their status line could display: Cost: $0.45 | Tokens: 50K in / 12K out | Cache: 80% hit rate
4. This would help them immediately see when they're approaching limits without interrupting their flow
5. They could optimize their workflow (e.g., use more caching, reduce context) based on real-time feedback

Additional Context

• The status line documentation is available at: https://docs.claude.com/en/docs/claude-code/statusline.md
• According to CHANGELOG.md line 136-138, session cost info was added to the status line API in v1.0.85, but token-level details were not included
• The /cost command already tracks these metrics internally, so this would be exposing existing data through the status line API
• This aligns with the existing pattern of providing detailed metrics in the cost object