semvec/pypi-packages huggingface dataset:
codex-usage-monitor 1.0.3
Monitor your Codex CLI token usage in real-time
License: MIT
Requires Python: >=3.8
Keywords: codex, codex-cli, usage, usage-monitor, token, token-usage, rate-limit, limits, monitoring, realtime, cli, terminal, tui, devtools, developer-tools, uv, uvx, pipx, observability, dashboard

# Codex Usage Monitor

Monitor Codex CLI token usage in real time from your terminal.

![Codex Usage Monitor demo](https://raw.githubusercontent.com/Coldsewoo/codex-usage-monitor/main/assets/codex-demo.png)

## Features

- 📊 5-hour and weekly usage tracking
- 🔥 Recent session activity
- 🔮 Usage predictions

## Installation

### With uvx (recommended)

Run directly without installing globally:

```bash
uvx codex-usage-monitor
```

If developing locally, run from the repo:

```bash
uvx --from . codex-usage-monitor
```

### From PyPI

```bash
pip install codex-usage-monitor
```

### From source

```bash
git clone https://github.com/Coldsewoo/codex-usage-monitor
cd codex-usage-monitor
pip install .
```

### Development mode

```bash
pip install -e .
```

## Usage

After installation, run:

```bash
# Canonical entry
uvx codex-usage-monitor

# Installed script aliases
codex-usage-monitor
codex-monitor
cmon

# Module form
python -m codex_monitor
```

The monitor will:
1. Read your token from `~/.codex/auth.json`
2. Display current usage for 5-hour and weekly windows
3. Show recent sessions with token counts
4. Auto-refresh every 30 seconds

Press `Ctrl+C` to exit.

### CLI options

```bash
codex-usage-monitor --help

  --interval <seconds>   Refresh interval in seconds (default: 10)
  --once                 Fetch and display once, then exit
  --json                 Print raw JSON usage and exit
  --version              Print version and exit
```

## Requirements

- Python 3.9+
- Codex CLI (logged in)

## Building from Source

### Build the package

```bash
# Install build tools
pip install build

# Build distribution packages
python -m build
```

This creates versioned wheel and sdist files in `dist/`.

### Install from wheel

```bash
pip install dist/codex_usage_monitor-{version_number}-py3-none-any.whl
```

### Using uvx (no installation)

```bash
# Run directly from local source
uvx --from . codex-usage-monitor

# Or from a built artifact
uvx --from dist/codex_usage_monitor-{version_number}-py3-none-any.whl codex-usage-monitor
```

## Publishing to PyPI

```bash
# Install twine
pip install twine

# Check distribution
twine check dist/*

# Upload to PyPI
twine upload dist/*
```

## Troubleshooting

### uvx picks an old version

**"Codex auth file not found"**
- Login to Codex CLI first: `codex`

**"Token refresh failed"**
- Re-login to Codex CLI: `codex`

**"Module 'requests' not found"**
- Install: `pip install requests`

**Build errors**
- Clean: `rm -rf build/ dist/ *.egg-info`
- Update tools: `pip install --upgrade build setuptools wheel`

## License

MIT