Expose token usage data to statusline scripts

Feature Request: Expose Token Usage Data to Statusline Scripts

Summary

Request to expose granular token usage information (tokens used, tokens remaining, max tokens) to custom statusline scripts via the JSON context object.

Current Behavior

The JSON object passed to custom statusline scripts (via statusLine.command) currently includes:

{
  "session_id": "...",
  "transcript_path": "...",
  "cwd": "/workspace",
  "model": {
    "id": "claude-sonnet-4-5-20250929",
    "display_name": "Sonnet 4.5"
  },
  "workspace": {
    "current_dir": "/workspace",
    "project_dir": "/workspace"
  },
  "version": "2.0.37",
  "output_style": {"name": "default"},
  "cost": {
    "total_cost_usd": 4.267483249999999,
    "total_duration_ms": 2257641,
    "total_api_duration_ms": 951022,
    "total_lines_added": 2109,
    "total_lines_removed": 103
  },
  "exceeds_200k_tokens": false
}

What's Missing

Token usage information is not included, despite being:

1. Tracked internally by Claude Code
2. Displayed in system warnings to Claude (e.g., "Token usage: 132107/200000; 67893 remaining")
3. Used to determine the exceeds_200k_tokens flag

The only token-related field is the boolean exceeds_200k_tokens, which provides insufficient granularity for creating informative statuslines.

Requested Behavior

Add token usage fields to the statusline JSON context:

{
  "session_id": "...",
  "model": { ... },
  "workspace": { ... },
  "tokens": {
    "used": 132107,
    "max": 200000,
    "remaining": 67893,
    "percentage_used": 66.0535,
    "percentage_remaining": 33.9465
  },
  "exceeds_200k_tokens": false,
  "cost": { ... }
}

Proposed Fields

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| tokens.used | number | Total tokens used in current context window | 132107 |
| tokens.max | number | Maximum tokens for the current model | 200000 |
| tokens.remaining | number | Tokens remaining before auto-compact | 67893 |
| tokens.percentage_used | number | Percentage of context used (0-100) | 66.0535 |
| tokens.percentage_remaining | number | Percentage of context remaining (0-100) | 33.9465 |

Note: The percentage fields could be optional if consumers prefer to calculate them from used and max.

Use Cases

1. Context Percentage Display

Show users exactly how much context remains:

# Statusline output: "user | project master | 33.9% | Sonnet 4.5"
context_pct=$(echo "$input" | jq -r '.tokens.percentage_remaining')
printf "%s | %s | %.1f%% | %s" "$user" "$project" "$context_pct" "$model"

2. Visual Warnings

Change statusline color/styling when context is running low:

tokens_remaining=$(echo "$input" | jq -r '.tokens.remaining')
if [ "$tokens_remaining" -lt 20000 ]; then
  color="\033[1;31m"  # Red when < 10% remaining
elif [ "$tokens_remaining" -lt 50000 ]; then
  color="\033[1;33m"  # Yellow when < 25% remaining
else
  color="\033[1;32m"  # Green otherwise
fi

3. Precise Token Count Display

Show exact token usage for power users:

# Statusline output: "132K/200K tokens | Sonnet 4.5"
tokens_used=$(echo "$input" | jq -r '.tokens.used')
tokens_max=$(echo "$input" | jq -r '.tokens.max')
printf "%dK/%dK tokens | %s" $((tokens_used/1000)) $((tokens_max/1000)) "$model"

4. Context Budget Awareness

Help users manage their context budget more effectively:

# Statusline output: "67K tokens left"
tokens_remaining=$(echo "$input" | jq -r '.tokens.remaining')
printf "%dK tokens left" $((tokens_remaining/1000))

Benefits

1. User Experience: Users can see exactly how much context they have left
2. Consistency: Aligns with the token usage data already shown in system warnings
3. Customization: Enables power users to create sophisticated statuslines
4. No Breaking Changes: Additive change - existing statusline scripts continue to work
5. Performance: No additional computation needed - data is already tracked internally

Workarounds Attempted

1. Parse Transcript File

Attempted: Calculate token usage by parsing the JSONL transcript file and summing usage fields.

Problems:

• Transcript contains per-message token counts, not cumulative context window usage
• Cache read tokens make cumulative calculation complex
• Performance impact of parsing large transcript files on every statusline refresh
• Doesn't account for auto-compaction events

2. Use exceeds_200k_tokens Flag

Attempted: Display binary state (under/over 200k).

Problems:

• Insufficient granularity (shows 100% until exactly 200k, then 0%)
• Doesn't help users manage context proactively
• No warning when approaching limit

3. Manual Token Tracking

Attempted: Maintain external token counter.

Problems:

• Requires intercepting all API calls
• Can't account for cache reads
• Breaks on auto-compaction
• Not reliable or maintainable

Implementation Notes

• The data is already available internally (as evidenced by system warnings)
• Minimal code change - just expose existing internal state to statusline JSON
• Backward compatible - new fields are optional
• Could be gated behind a feature flag if desired

Related Features

This aligns with other statusline context data already exposed:

• ✅ cost.total_cost_usd - Financial budget tracking
• ✅ cost.total_duration_ms - Time tracking
• ✅ exceeds_200k_tokens - Boolean token limit flag
• ❌ tokens.used / tokens.remaining - Missing granular token usage

Token usage is as important (if not more so) than cost tracking for user experience.

Priority

Medium-High

While there are workarounds (showing ~% or just the boolean flag), providing accurate token usage data significantly improves the user experience and enables better context management.

Example Integration

Once implemented, a statusline script could provide rich context information:

#!/bin/bash
input=$(cat)

# Extract token data
tokens_remaining=$(echo "$input" | jq -r '.tokens.remaining')
tokens_pct=$(echo "$input" | jq -r '.tokens.percentage_remaining')

# Color based on remaining tokens
if [ "$tokens_remaining" -lt 20000 ]; then
  indicator="🔴"
elif [ "$tokens_remaining" -lt 50000 ]; then
  indicator="🟡"
else
  indicator="🟢"
fi

# Output: "user | project master | 🟢 33.9% | Sonnet 4.5"
printf "%s | %s %s | %.1f%% | %s" \
  "$user" "$project" "$branch" "$indicator" "$tokens_pct" "$model"

Community Impact

This feature would benefit:

• Power users who monitor context usage closely
• Teams managing token budgets across sessions
• Users working on long-running projects
• Anyone who wants better visibility into their context window

References

• Current statusline documentation: docs.claude.com/claude-code/customization/statusline
• System warning format showing token data is already tracked internally
• Related issue: Users requesting better context visibility

---

Submitted by: Claude Code User
Date: 2025-11-13
Version: 2.0.37
Platform: Linux