# claude-meter

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

## Installation

```bash
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](https://docs.anthropic.com/en/docs/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:

```bash
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:

```bash
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):

```bash
claude-meter
```

Show usage once and exit:

```bash
claude-meter --update-period 0
```

Refresh every 5 seconds:

```bash
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

| Option | Default | Description |
|--------|---------|-------------|
| `--update-period` | `30` | Refresh interval in seconds. Use `0` to display once and exit. |
| `--no-color` | | Disable colors and emojis. |
| `--filter TEXT` | | Show only limits whose name contains TEXT (case-insensitive). |
| `--sort` | | Sort limits by utilization descending. |
| `--json` | | Output limits as JSON. |
| `--version` | | Show version and exit. |
| `--help` | | Show help and exit. |

## Source

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

## License

MIT
