A Java utility for retrieving Claude Code OAuth usage statistics from the Anthropic API.

This utility reads your local Claude Code credentials and queries the Anthropic API to retrieve your subscription utilization data, including:

• 5-hour rolling window - Short-term usage limit
• 7-day rolling window - Weekly usage limit
• 7-day Sonnet - Sonnet-specific weekly usage
• 7-day Opus - Opus-specific weekly usage (if applicable)
• Extra usage - Overage information

• Java 17 or higher
• Claude Code installed and authenticated (~/.claude/.credentials.json must exist)

git clone https://github.com/StephenLReed/claude-code-usage.git
cd claude-code-usage
mvn package

<dependency>
  <groupId>io.github.stephenreed</groupId>
  <artifactId>claude-code-usage</artifactId>
  <version>1.0.0</version>
</dependency>

Run the shaded JAR to display current usage statistics:

java -jar target/claude-code-usage-1.0.0.jar

Example output:

Claude Code Usage Statistics:
{
  "five_hour" : {
    "utilization" : 0.15,
    "resets_at" : "2025-01-05T17:00:00Z"
  },
  "seven_day" : {
    "utilization" : 0.42,
    "resets_at" : "2025-01-12T00:00:00Z"
  },
  "seven_day_sonnet" : {
    "utilization" : 0.38,
    "resets_at" : "2025-01-12T00:00:00Z"
  },
  "extra_usage" : {
    "enabled" : false,
    "used" : 0
  }
}

import io.github.stephenreed.claudecode.ClaudeCodeUsage;
import io.github.stephenreed.claudecode.ClaudeCodeUsageException;
import com.fasterxml.jackson.databind.JsonNode;

// Get full usage data
try {
    JsonNode usage = ClaudeCodeUsage.getClaudeCodeUsage();

    // Access specific fields
    double fiveHour = usage.path("five_hour").path("utilization").asDouble();
    double sevenDay = usage.path("seven_day").path("utilization").asDouble();

    System.out.printf("5-hour: %.1f%%, 7-day: %.1f%%\n",
        fiveHour * 100, sevenDay * 100);

} catch (ClaudeCodeUsageException e) {
    System.err.println("Failed to get usage: " + e.getMessage());
}

// Or use convenience methods
double fiveHourUtil = ClaudeCodeUsage.getFiveHourUtilization();
double sevenDayUtil = ClaudeCodeUsage.getSevenDayUtilization();

Thrown when:

• Credentials file not found (~/.claude/.credentials.json)
• Credentials file is malformed
• API request fails
• API returns non-200 status

1. Reads the OAuth access token from ~/.claude/.credentials.json
2. Makes an authenticated GET request to https://api.anthropic.com/api/oauth/usage
3. Returns the JSON response containing utilization data

The utility looks for credentials at:

• Linux/macOS: ~/.claude/.credentials.json
• Windows: %USERPROFILE%\.claude\.credentials.json

This file is created automatically when you authenticate with Claude Code.

Apache License 2.0

Stephen L. Reed - GitHub