📊 claude-usage

A command-line tool to quickly check your Claude Code usage statistics.

Overview

This Python script launches Claude Code in a PTY, sends the /usage command, captures the output, and displays your usage statistics in a clean format. It supports both human-readable text output and JSON format for scripting.

Installation

Prerequisites

• Python 3.6+
• pexpect library
• Claude Code CLI installed and authenticated

pip install pexpect

Setup

1. Clone this repository:

   git clone https://github.com/yourusername/claude-usage.git
   cd claude-usage

2. Make the script executable:

   chmod +x claude-usage

3. Optionally, add to your PATH or create a symlink:

   ln -s $(pwd)/claude-usage /usr/local/bin/claude-usage

Usage

Basic Usage

./claude-usage

Output:

Current session
42% used
Resets 7:59pm (America/Los_Angeles)

Current week (all models)
15% used
Resets Dec 1 at 11:59am (America/Los_Angeles)

Current week (Sonnet only)
8% used
Resets Dec 1 at 11:59am (America/Los_Angeles)

JSON Output

./claude-usage --json

Output:

{
  "timestamp": "2024-11-29T14:30:00.123456",
  "session": {
    "percent_used": 42,
    "resets_at": "2024-11-29T19:59:00",
    "timezone": "America/Los_Angeles"
  },
  "week_all_models": {
    "percent_used": 15,
    "resets_at": "2024-12-01T11:59:00",
    "timezone": "America/Los_Angeles"
  },
  "week_sonnet_only": {
    "percent_used": 8,
    "resets_at": "2024-12-01T11:59:00",
    "timezone": "America/Los_Angeles"
  }
}

Debug Mode

./claude-usage --debug

This prints detailed debug information to stderr while running.

Combine Options

./claude-usage --json --debug

How It Works

1. Spawns Claude Code in a pseudo-terminal (PTY) using pexpect
2. Waits for the CLI to initialize
3. Sends the /usage command
4. Waits for the usage screen to load
5. Captures and parses the screen output
6. Cleans up ANSI escape sequences
7. Extracts usage percentages and reset times
8. Outputs in the requested format (text or JSON)

Use Cases

• Quick status check: See your usage at a glance
• Scripting: Use --json output to integrate with other tools
• Monitoring: Schedule periodic checks to track usage patterns
• Automation: Trigger alerts when usage exceeds thresholds

License

MIT License