[FEATURE] Expose Usage Metrics in Session JSON

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Overview

Currently, Claude Code provides usage data in the Anthropic web UI (Settings > Usage) with detailed reset times and percentage-based metrics. However, this data is not exposed to Claude Code agents in the session JSON sent during execution.

We request that usage metrics be included in the session JSON payload so that:

1. Claude can implement intelligent usage monitoring in the statusline and other tools
2. Scripts can make decisions based on real-time usage data
3. Teams can build custom usage dashboards and alerts

Current State (Web UI)

Anthropic's web UI displays:

• Current session: Usage % with reset time
• Weekly limits: Usage % across all models with reset schedule
• Opus only: Separate usage tracking for Opus-specific limits
• Real-time last-updated timestamp

Example from Settings > Usage:

Plan usage limits

Current session
2% used
Resets in 3 hr 43 min

Weekly limits
All models: 59% used (Resets Thu 10:59 PM)
Opus only: 100% used (Resets Thu 9:59 PM)

Last updated: 1 minute ago

Existing Implementation (statusline.sh)

Currently, at P{redictable Data we manually cache usage % in /tmp/claude-usage-cache and implement our own time-since-reset calculation in genies/configs/claude-code-settings/statusline.sh:

# Current workaround: manually cache usage % from /cache-usage command
USAGE_PCT=$(cat "$USAGE_CACHE" 2>/dev/null | tr -d '\n')

# Calculate time % ourselves (generalized reset schedule)
NOW=$(date +%s)
RESET_DOW=4          # Thursday
RESET_HOUR=23
RESET_MIN=0

# ... complex date math to calculate elapsed time since last reset ...
TIME_PCT=$((ELAPSED_SECS * 100 / TOTAL_SECS))

# Project final usage
PROJECTED=$((USAGE_PCT * 100 / TIME_PCT))

This approach is:

• ❌ Disconnected: Manual cache system with separate /cache-usage command
• ❌ Unreliable: Depends on external file state and manual updates
• ❌ Fragile: Complex date calculations duplicated across tools
• ❌ Limited: No access to reset times or detailed metrics from Anthropic API

Proposed Solution

Add usage metrics to the session JSON payload sent to Claude Code agents. Extend the existing session data structure:

{
  "session_id": "2c5d8bd2-16ac-4087-9f28-796eb02f0860",
  "cwd": "/home/dwayne/pd/pd-shared",
  "model": {
    "id": "claude-sonnet-4-5-20250929",
    "display_name": "Sonnet 4.5"
  },
  "version": "2.0.45",
  "exceeds_200k_tokens": false,

  "usage_metrics": {
    "current_session": {
      "percent_used": 2,
      "tokens_used": 4_200,
      "tokens_limit": 200_000,
      "resets_in_seconds": 13_423,
      "reset_timestamp": 1_731_973_200
    },
    "weekly_limits": {
      "all_models": {
        "percent_used": 59,
        "tokens_used": 590_000,
        "tokens_limit": 1_000_000,
        "resets_in_seconds": 86_400,
        "reset_timestamp": 1_731_982_800,
        "reset_day": "Thursday",
        "reset_time": "22:59"
      },
      "opus_only": {
        "percent_used": 100,
        "tokens_used": 150_000,
        "tokens_limit": 150_000,
        "resets_in_seconds": 72_000,
        "reset_timestamp": 1_731_968_400,
        "reset_day": "Thursday",
        "reset_time": "21:00"
      }
    },
    "last_updated_timestamp": 1_731_908_952,
    "last_updated_seconds_ago": 12
  }
}

Benefits

1. Direct API Access: Agents receive authoritative usage data from Anthropic's backend
2. Simplified Tooling: No need for manual cache files or separate /cache-usage commands
3. Rich Metrics: Access to reset times, token counts, and percentage data
4. Real-time Decisions: Scripts can implement usage-aware throttling, warnings, or fallback logic
5. Monitoring: Easy integration with dashboards, Prometheus metrics, or alerting systems

Use Cases

1. Intelligent Statusline (Current Implementation)

Instead of:

# Manual cache + complex date math
USAGE_PCT=$(cat /tmp/claude-usage-cache)
TIME_PCT=$((ELAPSED_SECS * 100 / TOTAL_SECS))
PROJECTED=$((USAGE_PCT * 100 / TIME_PCT))

We could write:

USAGE_PCT=$(echo "$INPUT" | jq -r '.usage_metrics.weekly_limits.all_models.percent_used')
TIME_PCT=$(echo "$INPUT" | jq -r '.usage_metrics.weekly_limits.all_models | ((.resets_in_seconds / 604800) * 100) | 100 - .')
PROJECTED=$((USAGE_PCT * 100 / TIME_PCT))

Or even simpler in a script:

usage_pct=$(jq '.usage_metrics.weekly_limits.all_models.percent_used' /dev/stdin)
time_pct=$(jq '.usage_metrics.weekly_limits.all_models | ... calculate ...' /dev/stdin)

2. Usage-Aware Task Decisions

An agent could check usage before starting resource-intensive tasks:

usage=$(jq '.usage_metrics.weekly_limits.all_models.percent_used' <<< "$SESSION_JSON")
if [ "$usage" -gt 80 ]; then
  echo "⚠️  Usage is at ${usage}%—consider using cheaper models or deferring this task"
  exit 1
fi

3. Automated Warnings

Build alerting into hooks:

# Post-tool-reminders-hook.sh could check usage and warn if:
# - usage > 90%: "Approaching limit!"
# - time_percent > usage_percent: "Pacing well, on track to be under limits"
# - time_percent < usage_percent: "Usage running hot—may exceed weekly limit"

4. Team Dashboards

Aggregate usage metrics across team members:

# Could POST usage_metrics to internal monitoring system
curl -X POST https://internal.monitoring.local/usage \
  -d "$(jq '.usage_metrics' <<< "$SESSION_JSON")"

Implementation Notes

No breaking changes required:

• New usage_metrics field is optional
• Existing session JSON fields remain unchanged
• Graceful fallback: scripts check for field existence before use

Scope:

• Current session metrics (token-level granularity, optional)
• Weekly limits (all models + Opus-only)
• Reset times (timestamps and human-readable formats)
• Last updated timestamp (for cache freshness checking)

Frequency:

• Include in every session JSON payload
• Refresh periodically (every N minutes, or on-demand if API supports)
• Include last_updated_timestamp so scripts can detect stale data

Questions for Claude Code Team

1. Is usage data available in Claude Code's internal API/backend?
2. Could this be included in the session JSON without significant performance impact?
3. What's the refresh frequency of usage data in the web UI (1 min? Real-time)?
4. Would token-level granularity be feasible, or just percentage-based metrics?
5. Any privacy/security considerations for exposing usage data to local scripts?

---

Additional Enhancement: Usage Metrics as First-Class Config

Suggestion: Consider making usage metrics available through:

1. Environment variables (e.g., CLAUDE_USAGE_PCT, CLAUDE_RESET_IN_SECS)
2. Status line helper function for easy formatting
3. Optional .claude/usage-metrics.json file updated by Claude Code

This would support multiple consumption patterns beyond just session JSON.

Corollary Feature: Add the % time passed since last reset to the https://claude.ai/settings/usage page, too.

Proposed Solution

See above -- Claude created a full md for me... Copy/paste surgery didn't seem necessary.

Alternative Solutions

See above

Priority

Low - Nice to have

Feature Category

CLI commands and flags

Use Case Example

See above

Additional Context

See above