Metadata-Version: 2.4
Name: claude-usage-cli
Version: 1.2.0
Summary: Monitor Claude AI token usage with zero dependencies
Author-email: jedarden <github@jedarden.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jedarden/claude-usage-monitor-cli
Project-URL: Repository, https://github.com/jedarden/claude-usage-monitor-cli
Project-URL: Issues, https://github.com/jedarden/claude-usage-monitor-cli/issues
Project-URL: Changelog, https://github.com/jedarden/claude-usage-monitor-cli/blob/main/CHANGELOG.md
Keywords: claude,api,usage,monitoring,cli,token
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Claude Usage Monitor (Python Package)

Professional CLI tool for monitoring Claude AI token usage with **zero external dependencies**.

## Credits & Attribution

This package is based on the original **[Claude-Code-Usage-Monitor](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor)** by **[Maciej](https://github.com/Maciek-roboblog)** (maciek@roboblog.eu). This version transforms it into a zero-dependency pip-installable package while maintaining all original functionality.

## Installation

```bash
# Run without installing anything (recommended)
uvx claude-usage-cli

# Or install it
uv tool install claude-usage-cli
pip install claude-usage-cli
```

The package has zero dependencies, so `uvx` fetches and runs it in one step
with no virtualenv to manage:

```bash
uvx claude-usage-cli --summary
uvx claude-usage-cli --plan max20 --weekly-limit 4000
```

## Quick Start

```bash
# Default monitoring (Pro plan)
claude-usage-cli

# Monitor with Max5 plan
claude-usage-cli --plan max5

# Custom timezone
claude-usage-cli --plan max20 --timezone US/Eastern

# Track against your own weekly limit
claude-usage-cli --weekly-limit 2000

# Show help
claude-usage-cli --help
```

## Features

- 📊 **Real-time token monitoring** with visual progress bars
- 🔮 **Smart predictions** based on usage patterns
- 🎯 **Multi-plan support** (Pro, Max5, Max20, Custom)
- 🌍 **Timezone handling** for accurate reset times
- 🎨 **Beautiful terminal UI** with colors and emojis
- ⚡ **Zero external dependencies** - completely self-contained
- 🔄 **Auto-refresh** every 3 seconds
- 📱 **Cross-platform** (Windows, macOS, Linux)

## Commands

```bash
# Basic usage
claude-usage-cli                          # Start monitoring with Pro plan
claude-usage-cli --plan max5              # Monitor with Max5 plan
claude-usage-cli --once                   # Run once and exit
claude-usage-cli --summary                # Show summary only

# Configuration
claude-usage-cli --list-plans             # Show available plans
claude-usage-cli --list-timezones         # Show timezone options
claude-usage-cli --info                   # Show configuration info

# Customization
claude-usage-cli --timezone US/Pacific    # Set timezone
claude-usage-cli --limit-per-5h 60        # Override the 5-hour estimate
claude-usage-cli --weekly-limit 2000      # Track against your own weekly limit
claude-usage-cli --refresh 5              # Set refresh interval
claude-usage-cli --no-color               # Disable colors
```

## Limits

Claude enforces **two** limits, and neither of them is a daily limit:

| Window | How it works |
|---|---|
| **5-hour session** | Opens at your first message and runs for five hours. |
| **Weekly** | Resets seven days after your first message of the week. |

Releases up to 1.1.2 displayed a *daily* limit instead of the weekly one. It
did not correspond to anything Claude enforces, and the per-plan numbers
behind it were invented. Both are fixed in 1.2.0.

### Plans supported

| Plan | 5-hour estimate | Weekly |
|---|---|---|
| `pro` | ~45 messages | set with `--weekly-limit` |
| `max5` | ~225 messages | set with `--weekly-limit` |
| `max20` | ~900 messages | set with `--weekly-limit` |
| `custom` | set with `--limit-per-5h` | set with `--weekly-limit` |

The 5-hour figures are Anthropic's published **estimates** for average-length
chats; real capacity moves with message size, context length, attachments and
model, so the output labels them `est.`. Override with `--limit-per-5h`.

Weekly limits have no default on purpose. Anthropic publishes them as ranges
of model *hours*, not as a message count, so there is no honest conversion
into the message counter this tool keeps. Without `--weekly-limit` the weekly
section still reports real usage — messages, tokens, sessions, burn rate and
when your oldest activity rolls off — just without a percentage bar. Supply
`--weekly-limit N` once you know where yours actually bites and you get the
bar and a projection.

## How It Works

This package reads Claude's conversation logs directly from your local filesystem:

- **Location**: `~/.config/claude/projects/` (Unix) or `%APPDATA%\claude\` (Windows)
- **Format**: JSONL files containing conversation data
- **Processing**: Extracts token usage and groups it into 5-hour session
  windows anchored to your first message (not to fixed slices of the clock)
- **Predictions**: Analyzes usage patterns to predict future consumption

## Zero Dependencies

This package uses only Python's built-in libraries:

- `datetime` for timezone handling (no pytz needed)
- `json` for parsing JSONL files
- `argparse` for CLI interface
- `os`/`sys` for system operations

## Requirements

- Python 3.7+
- Claude Desktop installed and used at least once
- Access to Claude's local data directory

## Development

```bash
# Clone repository
git clone https://github.com/jedarden/claude-usage-monitor-cli.git
cd claude-usage-monitor-cli/python

# Install in development mode
pip install -e .

# Run the test suite (stdlib unittest, no dependencies)
python -m unittest discover -s tests -v

# Run directly
python -m claude_monitor.cli --help
```

## License

MIT License - see LICENSE file for details.
