Expose token usage data to statusline scripts

[attaris-base]

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

[JoMiPeCa]

Have yoiu notice recently that claude is using a lot more tokens ?

My sessions have been consuming more tokens than before and claude performance is degraded...

[polczak-itt]

The ccstatusline project (which is the most popular way of configuring custom complex status lines for Claude Code) uses some inaccurate estimates for showing its users current context usage % and implementing this feature request is the only option to improve the situation (rel: https://github.com/sirmalloc/ccstatusline/issues/109#issuecomment-3544060114)

[darnoxx]

As a Claude Code Max plan user, the inability to display /context data (current context window usage) in the statusline remains a major disappointment.

Key points:

1. The v2.0.65 "context window info" feature is misleading - it provides cumulative API call totals, not actual context window state—NOT applicable to Max plan users
2. Max plan users with 200k context windows need to monitor how close they are to the limit
3. The data exists (shown by /context command) but isn't exposed to statusline scripts
4. This makes the statusline token display feature essentially useless for its intended purpose

Requested feature: Expose the same data that /context displays (current tokens used / context window size) to statusline command scripts.