llm-usage

README

llm-usage

A CLI tool to display your LLM API usage statistics across multiple providers (Claude, Kimi, Z.AI).

Features

• View real-time usage statistics from multiple LLM providers
• Multiple output formats: pretty-printed, JSON, and Waybar-compatible
• Visual progress bars showing usage utilization
• Displays reset times for usage windows
• Filter by provider or view all at once

Prerequisites

For Claude usage, you must have the Claude CLI installed and authenticated.

Installation

From Source

go install github.com/denysvitali/llm-usage@latest

From Releases

Download the appropriate binary for your platform from the Releases page.

Usage

# Show all configured providers (default)
llm-usage

# Show specific provider
llm-usage --provider=claude
llm-usage --provider=kimi
llm-usage --provider=zai

# JSON output
llm-usage --json

# Waybar-compatible JSON output
llm-usage --waybar

# Show version
llm-usage --version

Configuration

Credentials are stored following the XDG Base Directory Specification:

• $XDG_CONFIG_HOME/llm-usage/claude.json - Claude OAuth credentials
• $XDG_CONFIG_HOME/llm-usage/kimi.json - Kimi API credentials
• $XDG_CONFIG_HOME/llm-usage/zai.json - Z.AI API credentials

On Linux/macOS, $XDG_CONFIG_HOME defaults to ~/.config if not set.

Migrating from claude-code-usage

# Create the config directory
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/llm-usage"

# Copy existing Claude credentials
cp ~/.claude/.credentials.json "${XDG_CONFIG_HOME:-$HOME/.config}/llm-usage/claude.json"

Example Output

LLM Usage Statistics
====================

Claude (Pro/Max Subscription):
--------------------------------
  5-Hour Window:
    Usage:    [████████████░░░░░░░░] 60.0%
    Resets:   in 2h 15m
  7-Day Window:
    Usage:    [██████░░░░░░░░░░░░░░] 30.0%
    Resets:   in 3d 5h

Kimi:
--------------------------------
  Error: API not yet configured or not implemented

Z.AI:
--------------------------------
  Daily Usage:
    Usage:    [████░░░░░░░░░░░░░░░] 20.0%
    Limit:    1000000 tokens

Waybar Integration

Add this to your Waybar config:

{
  "custom/llm-usage": {
    "exec": "llm-usage --waybar",
    "return-type": "json",
    "interval": 300
  }
}

Building from Source

# Clone the repository
git clone https://github.com/denysvitali/llm-usage.git
cd llm-usage

# Build
make build

# Or install directly
make install

Development

# Run linter
make lint

# Run tests
make test

# Build and test everything
make all

Supported Providers

Provider	Status	Notes
Claude	✅ Implemented	Requires Claude CLI OAuth credentials
Kimi	🔜 Planned	API endpoint identified, implementation pending
Z.AI	🔜 Planned	API endpoint identified, implementation pending

License

MIT License - see LICENSE for details.

Documentation

Overview

Package main provides the CLI for llm-usage.