/usage - Token Usage Summary

Display token usage metrics and cost estimation for the current session.

Usage

/usage                    # Show usage summary
/usage --json             # Output as JSON
/usage --export <path>    # Export to file
/usage --reset            # Reset tracking for new session

Output

The command displays:

1. Session Overview

   • Session ID
   • Start time
   • Total API calls

2. Token Metrics

   • Total input tokens
   • Total output tokens
   • Total tokens consumed
   • Cached tokens (if applicable)

3. Cost Estimation

   • Total estimated cost (USD)
   • Per-model breakdown

4. Per-Model Usage

   • Model name and provider
   • Number of calls
   • Input/output tokens
   • Estimated cost

Example Output

Token Usage Summary
==================

Session: abc123-def456
Started: 2026-01-16T14:30:00Z

Totals:
  Calls:         15
  Input Tokens:  45,230
  Output Tokens: 12,450
  Total Tokens:  57,680
  Est. Cost:     $0.2847

By Model:
  anthropic:claude-sonnet-4-5
    Calls: 10 | Input: 35,000 | Output: 10,000 | Cost: $0.2550
  openai:gpt-4o
    Calls: 5 | Input: 10,230 | Output: 2,450 | Cost: $0.0297

JSON Output

/usage --json

{
  "session_id": "abc123-def456",
  "started_at": "2026-01-16T14:30:00Z",
  "total_calls": 15,
  "total_input_tokens": 45230,
  "total_output_tokens": 12450,
  "total_tokens": 57680,
  "cost_estimate": {
    "total_estimated_usd": 0.2847,
    "by_model": {
      "anthropic:claude-sonnet-4-5": 0.255,
      "openai:gpt-4o": 0.0297
    }
  },
  "model_usage": {
    "anthropic:claude-sonnet-4-5": {
      "model": "claude-sonnet-4-5",
      "provider": "anthropic",
      "num_calls": 10,
      "input_tokens": 35000,
      "output_tokens": 10000,
      "cached_tokens": 0,
      "total_tokens": 45000
    }
  }
}

Integration

Automatic Export

Token usage is automatically appended to session exports:

/export my-session   # Usage metrics included at end

Hook Integration

The hooks/export-with-metrics.py hook automatically adds usage summaries to exports.

MoE Judge Panel

The MultiModelClient (ADR-073) automatically records token usage from all MoE judge evaluations.

Implementation

Component	Path	Purpose
Usage Tracker	scripts/core/usage_tracking.py	Core tracking classes
Cost Estimator	scripts/core/cost_estimator.py	Cost calculation
Model Pricing	config/model-pricing.json	Price configuration
Export Hook	hooks/export-with-metrics.py	Export integration

Pricing Reference

Pricing is loaded from config/model-pricing.json. Current rates (January 2026):

Model	Provider	Input ($/1M)	Output ($/1M)
claude-opus-4-5	Anthropic	$15.00	$75.00
claude-sonnet-4-5	Anthropic	$3.00	$15.00
claude-haiku-4-5	Anthropic	$0.80	$4.00
gpt-4.1	OpenAI	$2.00	$8.00
deepseek-v3.2	DeepSeek	$0.27	$1.10
gemini-3-pro	Google	$1.25	$5.00

Update pricing by editing config/model-pricing.json.

Related

• ADR: ADR-075
• Skill: token-cost-tracking
• MoE Integration: ADR-073