Cost & Usage Monitoring

Overview

Cost monitoring displays your current API costs with hourly burn rate calculations, helping you understand spending patterns and optimize usage.

Requires jq for full functionality. Basic cost display works without jq, but burn rate calculations require it.

What You See

💰 $49.00 ($16.55/h)  📊 14638846 tok (279900 tpm)

The display includes:

💰 Current total cost in USD
💵 Burn rate (cost per hour)
📊 Total tokens consumed
⚡ Token burn rate (tokens per minute)

Cost Tracking

Data Source

Cost data comes from Claude Code’s native cost tracking:

{
  "cost": {
    "total_cost_usd": 49.00,
    "total_duration_ms": 10677000
  },
  "context_window": {
    "total_input_tokens": 12500000,
    "total_output_tokens": 2138846
  }
}

Implementation

From features/usage.ts:36-88:

With jq (Recommended)
Bash Fallback

# Cost data
cost_usd=$(echo "$input" | jq -r '.cost.total_cost_usd // empty' 2>/dev/null)
total_duration_ms=$(echo "$input" | jq -r '.cost.total_duration_ms // empty' 2>/dev/null)

# Calculate burn rate ($/hour) from cost and duration
if [ -n "$cost_usd" ] && [ -n "$total_duration_ms" ] && [ "$total_duration_ms" -gt 0 ]; then
  cost_per_hour=$(echo "$cost_usd $total_duration_ms" | awk '{printf "%.2f", $1 * 3600000 / $2}')
fi

Burn rate calculation:

Formula: (total_cost / total_duration_ms) × 3600000
Converts milliseconds to hours (3600000 ms = 1 hour)
Results in dollars per hour

# Bash fallback for cost extraction
cost_usd=$(echo "$input" | grep -o '"total_cost_usd"[[:space:]]*:[[:space:]]*[0-9.]*' | sed 's/.*:[[:space:]]*\([0-9.]*\).*/\1/')
total_duration_ms=$(echo "$input" | grep -o '"total_duration_ms"[[:space:]]*:[[:space:]]*[0-9]*' | sed 's/.*:[[:space:]]*\([0-9]*\).*/\1/')

# Calculate burn rate (same formula as with jq)
if [ -n "$cost_usd" ] && [ -n "$total_duration_ms" ] && [ "$total_duration_ms" -gt 0 ]; then
  cost_per_hour=$(echo "$cost_usd $total_duration_ms" | awk '{printf "%.2f", $1 * 3600000 / $2}')
fi

The bash fallback uses regex patterns and may be less reliable than jq.

Burn Rate Calculation

Understanding burn rate formula

Why multiply by 3600000?The formula converts cost per millisecond to cost per hour:

cost_per_hour = (total_cost_usd / total_duration_ms) × 3600000

Breaking it down:

total_cost_usd / total_duration_ms = cost per millisecond
Multiply by 1000 = cost per second
Multiply by 60 = cost per minute
Multiply by 60 = cost per hour
Total multiplier: 1000 × 60 × 60 = 3,600,000

Example:

Total cost: $49.00
Duration: 10,677,000 ms (≈ 2.97 hours)
Calculation: (49.00 / 10677000) × 3600000 = 16.52
Result: $16.52/hour

Token Analytics

Token tracking shows your total token consumption and burn rate.

Token Data Extraction

From features/usage.ts:50-82:

# Token data from native context_window (no ccusage needed)
input_tokens=$(echo "$input" | jq -r '.context_window.total_input_tokens // 0' 2>/dev/null)
output_tokens=$(echo "$input" | jq -r '.context_window.total_output_tokens // 0' 2>/dev/null)

if [ "$input_tokens" != "null" ] && [ "$output_tokens" != "null" ]; then
  tot_tokens=$(( input_tokens + output_tokens ))
  [ "$tot_tokens" -eq 0 ] && tot_tokens=""
fi

# Calculate tokens per minute from native data
if [ -n "$tot_tokens" ] && [ -n "$total_duration_ms" ] && [ "$total_duration_ms" -gt 0 ]; then
  # Convert ms to minutes and calculate rate
  tpm=$(echo "$tot_tokens $total_duration_ms" | awk '{if ($2 > 0) printf "%.0f", $1 * 60000 / $2; else print ""}')
fi

Token data comes from Claude Code’s native context_window object—no ccusage required for token stats!

Token Burn Rate Formula

tokens_per_minute = (total_tokens / total_duration_ms) × 60000

Where:

total_tokens = input_tokens + output_tokens
total_duration_ms = session duration in milliseconds
60000 = conversion factor (60,000 ms = 1 minute)

Display Implementation

From features/usage.ts:154-196:

export function generateUsageDisplayCode(config: UsageFeature, colors: boolean, emojis: boolean): string {
  const costEmoji = emojis ? '💵' : '$'
  const tokenEmoji = emojis ? '📊' : 'tok:'
  
  // Cost display
  if [ -n "$cost_usd" ] && [[ "$cost_usd" =~ ^[0-9.]+$ ]]; then
    if [ -n "$cost_per_hour" ] && [[ "$cost_per_hour" =~ ^[0-9.]+$ ]]; then
      printf '  ${costEmoji} %s$%.2f ($%.2f/h)%s' "$(cost_color)" "$cost_usd" "$cost_per_hour" "$(rst)"
    else
      printf '  ${costEmoji} %s$%.2f%s' "$(cost_color)" "$cost_usd" "$(rst)"
    fi
  fi
  
  // Token display
  if [ -n "$tot_tokens" ] && [[ "$tot_tokens" =~ ^[0-9]+$ ]]; then
    if [ -n "$tpm" ] && [[ "$tpm" =~ ^[0-9.]+$ ]]; then
      printf '  ${tokenEmoji} %s%s tok (%.0f tpm)%s' "$(usage_color)" "$tot_tokens" "$tpm" "$(rst)"
    else
      printf '  ${tokenEmoji} %s%s tok%s' "$(usage_color)" "$tot_tokens" "$(rst)"
    fi
  fi
}

Color Scheme

From features/usage.ts:14-30:

# ---- usage colors ----
usage_color() { if [ "$use_color" -eq 1 ]; then printf '\033[38;5;189m'; fi; }  # lavender
cost_color() { if [ "$use_color" -eq 1 ]; then printf '\033[38;5;222m'; fi; }   # light gold
burn_color() { if [ "$use_color" -eq 1 ]; then printf '\033[38;5;220m'; fi; }   # bright gold

Element	Color	ANSI Code	Purpose
Token count	Lavender	38;5;189	General usage info
Total cost	Light gold	38;5;222	Dollar amounts
Burn rate	Bright gold	38;5;220	Highlighted rates

Configuration

From cli/prompts.ts:28-30:

{ name: '💵 Usage & Cost', value: 'usage', checked: true },
{ name: '📊 Token Statistics', value: 'tokens', checked: true },
{ name: '⚡ Burn Rate ($/hr & tokens/min)', value: 'burnrate', checked: true }

All cost and usage features are enabled by default.

Example Outputs

Full Display
Cost Only
Tokens Only
No Burn Rates

# All metrics enabled
💰 $49.00 ($16.55/h)  📊 14638846 tok (279900 tpm)

Shows:

Total cost: $49.00
Hourly burn rate: $16.55/h
Total tokens: 14,638,846
Token burn rate: 279,900 tokens/minute

# Tokens disabled
💰 $2.48 ($12.50/h)

Shows cost and burn rate without token stats.

# Cost disabled, tokens enabled
📊 1523400 tok (45000 tpm)

Shows token consumption without cost.

# Burn rate feature disabled
💰 $5.23  📊 2450000 tok

Shows totals without per-hour/per-minute calculations.

Understanding Your Costs

Low Burn Rate

< $5/hourTypical for:

Code review sessions
Documentation work
Light development

Medium Burn Rate

$5-20/hourCommon for:

Active development
Large refactorings
Complex debugging

High Burn Rate

$20-50/hourHappens during:

Heavy code generation
Large file processing
Extensive context usage

Very High Burn Rate

> $50/hourConsider:

Starting fresh conversation
Reducing context size
Breaking into smaller tasks

Requirements

Feature	Requirement	Fallback
Cost display	jq recommended	Bash regex fallback available
Burn rate	jq + awk	Limited without jq
Token stats	jq recommended	Bash regex fallback available
Token burn rate	jq + awk	Not available without jq

Performance

Execution time: ~10-15ms with jq
Data source: Native Claude Code JSON (no external API calls)
Calculations: Simple arithmetic via awk
Overhead: Minimal

Troubleshooting

Cost not showing

Possible causes:

No cost data available yet (fresh conversation)
JSON extraction failed
jq not installed

Solutions:

Continue conversation to generate some usage
Install jq: brew install jq (macOS) or apt-get install jq (Linux)
Enable logging to debug JSON extraction

Burn rate showing as $0.00/h

Cause: Duration is zero or very smallNormal behavior: Early in a conversation, duration may be too small for meaningful burn rate calculation. The rate will stabilize after a few minutes of usage.

Token count seems wrong

Debug steps:

Enable debug logging during init
Check .claude/statusline.log for raw JSON
Verify context_window.total_input_tokens and total_output_tokens values
Formula: total = input + output tokens

Note: Token counts are cumulative for the entire conversation.

Burn rate fluctuates wildly

Normal behavior: Burn rate is calculated as average over total duration:

Early in conversation: Rate may seem high
During pauses: Rate decreases
During heavy usage: Rate increases

This is expected—it reflects your actual usage pattern over time.

Next Steps

Session Timer

Track time until usage reset

Customization

Customize display format and colors

Getting Started

Features

Guides

Overview

What You See

Cost Tracking

Data Source

Implementation

Burn Rate Calculation

Token Analytics

Token Data Extraction

Token Burn Rate Formula

Display Implementation

Color Scheme

Configuration

Example Outputs

Understanding Your Costs

Low Burn Rate

Medium Burn Rate

High Burn Rate

Very High Burn Rate

Requirements

Performance

Troubleshooting

Next Steps

Session Timer

Customization

Build docs developers (and LLMs) love

Getting Started

Features

Guides

​Overview

​What You See

​Cost Tracking

​Data Source

​Implementation

​Burn Rate Calculation

​Token Analytics

​Token Data Extraction

​Token Burn Rate Formula

​Display Implementation

​Color Scheme

​Configuration

​Example Outputs

​Understanding Your Costs

Low Burn Rate

Medium Burn Rate

High Burn Rate

Very High Burn Rate

​Requirements

​Performance

​Troubleshooting

​Next Steps

Session Timer

Customization

Build docs developers (and LLMs) love

Overview

What You See

Cost Tracking

Data Source

Implementation

Burn Rate Calculation

Token Analytics

Token Data Extraction

Token Burn Rate Formula

Display Implementation

Color Scheme

Configuration

Example Outputs

Understanding Your Costs

Requirements

Performance

Troubleshooting

Next Steps