claude-meter

Display your Claude.ai plan usage as ASCII meters in the terminal.

Installation

pip install claude-meter

Authentication

claude-meter needs an OAuth token to query your Claude.ai usage. It looks for credentials in the following order:

1. CLAUDE_CODE_OAUTH_TOKEN environment variable — if set, this value is used directly as the Bearer token.
2. ~/.claude/.credentials.json — the file created automatically when you log in with Claude Code. The tool reads the claudeAiOauth.accessToken field from this file.

Using Claude Code credentials (recommended)

If you already use Claude Code, no extra setup is needed — just make sure you are logged in:

claude   # log in if prompted

The credentials file is created at ~/.claude/.credentials.json and claude-meter will pick it up automatically.

Using an environment variable

If you prefer to supply the token yourself, export it before running the command:

export CLAUDE_CODE_OAUTH_TOKEN="your-token-here"
claude-meter

This is useful in CI, scripts, or environments where Claude Code is not installed.

Usage

Show usage and refresh every 30 seconds (default):

claude-meter

Show usage once and exit:

claude-meter --update-period 0

Refresh every 5 seconds:

claude-meter --update-period 5

Example Output

Claude Meter
--------------------------------------------------
  5-Hour Session
    [========>                     ]  27.0%  (resets in 3h 42m)

  7-Day Weekly
    [===========>                  ]  35.0%  (resets in 4d 2h)

  7-Day Opus
    [                              ]   0.0%  (no reset scheduled)

Options

Source

GitHub: https://github.com/breed/claude-meter

License

MIT