# Codex Usage Monitor
Monitor Codex CLI token usage in real time from your terminal.
## Features
- 📊 5-hour and weekly usage tracking
- 🔥 Recent session activity
- 🔮 Usage predictions
- 🔄 Automatic token refresh
- 🎨 Color-coded progress bars
## 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)
- `requests` library (auto-installed)
## 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-1.0.0-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/<your-wheel>.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
Raw data
{
"_id": null,
"home_page": null,
"name": "codex-usage-monitor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"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",
"author": null,
"author_email": "Coldsewoo <coldsewoo@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d4/2b/5be8ff6f6475321d1dfc3e6d09b301481e8560425edc5fce7c0c2447185c/codex_usage_monitor-1.0.2.tar.gz",
"platform": null,
"description": "# Codex Usage Monitor\n\nMonitor Codex CLI token usage in real time from your terminal.\n\n\n\n## Features\n\n- \ud83d\udcca 5-hour and weekly usage tracking\n- \ud83d\udd25 Recent session activity\n- \ud83d\udd2e Usage predictions\n- \ud83d\udd04 Automatic token refresh\n- \ud83c\udfa8 Color-coded progress bars\n\n## Installation\n\n### With uvx (recommended)\n\nRun directly without installing globally:\n\n```bash\nuvx codex-usage-monitor\n```\n\nIf developing locally, run from the repo:\n\n```bash\nuvx --from . codex-usage-monitor\n```\n\n### From PyPI\n\n```bash\npip install codex-usage-monitor\n```\n\n### From source\n\n```bash\ngit clone https://github.com/Coldsewoo/codex-usage-monitor\ncd codex-usage-monitor\npip install .\n```\n\n### Development mode\n\n```bash\npip install -e .\n```\n\n## Usage\n\nAfter installation, run:\n\n```bash\n# Canonical entry\nuvx codex-usage-monitor\n\n# Installed script aliases\ncodex-usage-monitor\ncodex-monitor\ncmon\n\n# Module form\npython -m codex_monitor\n```\n\nThe monitor will:\n1. Read your token from `~/.codex/auth.json`\n2. Display current usage for 5-hour and weekly windows\n3. Show recent sessions with token counts\n4. Auto-refresh every 30 seconds\n\nPress `Ctrl+C` to exit.\n\n### CLI options\n\n```bash\ncodex-usage-monitor --help\n\n --interval <seconds> Refresh interval in seconds (default: 10)\n --once Fetch and display once, then exit\n --json Print raw JSON usage and exit\n --version Print version and exit\n```\n\n## Requirements\n\n- Python 3.9+\n- Codex CLI (logged in)\n- `requests` library (auto-installed)\n\n## Building from Source\n\n### Build the package\n\n```bash\n# Install build tools\npip install build\n\n# Build distribution packages\npython -m build\n```\n\nThis creates versioned wheel and sdist files in `dist/`.\n\n### Install from wheel\n\n```bash\npip install dist/codex_usage_monitor-1.0.0-py3-none-any.whl\n```\n\n### Using uvx (no installation)\n\n```bash\n# Run directly from local source\nuvx --from . codex-usage-monitor\n\n# Or from a built artifact\nuvx --from dist/<your-wheel>.whl codex-usage-monitor\n```\n\n## Publishing to PyPI\n\n```bash\n# Install twine\npip install twine\n\n# Check distribution\ntwine check dist/*\n\n# Upload to PyPI\ntwine upload dist/*\n```\n\n## Troubleshooting\n\n### uvx picks an old version\n\n**\"Codex auth file not found\"**\n- Login to Codex CLI first: `codex`\n\n**\"Token refresh failed\"**\n- Re-login to Codex CLI: `codex`\n\n**\"Module 'requests' not found\"**\n- Install: `pip install requests`\n\n**Build errors**\n- Clean: `rm -rf build/ dist/ *.egg-info`\n- Update tools: `pip install --upgrade build setuptools wheel`\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Monitor your Codex CLI token usage in real-time",
"version": "1.0.2",
"project_urls": {
"homepage": "https://github.com/Coldsewoo/codex-usage-monitor",
"issues": "https://github.com/Coldsewoo/codex-usage-monitor/issues",
"repository": "https://github.com/Coldsewoo/codex-usage-monitor.git"
},
"split_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"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "325f9e58fa9279908a7cac528cdd450f45d6cc48238dc6650e3c548235b1f616",
"md5": "9cadfb1c586fd50e5bf1028996874984",
"sha256": "2443a2b22468f6710c2dad2ea76baedf068b58c369aca43f06c3016a8a9ab25d"
},
"downloads": -1,
"filename": "codex_usage_monitor-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9cadfb1c586fd50e5bf1028996874984",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11559,
"upload_time": "2025-10-27T08:28:02",
"upload_time_iso_8601": "2025-10-27T08:28:02.339485Z",
"url": "https://files.pythonhosted.org/packages/32/5f/9e58fa9279908a7cac528cdd450f45d6cc48238dc6650e3c548235b1f616/codex_usage_monitor-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d42b5be8ff6f6475321d1dfc3e6d09b301481e8560425edc5fce7c0c2447185c",
"md5": "dde88afe88e8b94e5fbc6e5e37691636",
"sha256": "f38c9052b73f4c2b2d9daf69b0361482a0ac847de7751ce0e835c1736ad81535"
},
"downloads": -1,
"filename": "codex_usage_monitor-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "dde88afe88e8b94e5fbc6e5e37691636",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10598,
"upload_time": "2025-10-27T08:28:03",
"upload_time_iso_8601": "2025-10-27T08:28:03.733020Z",
"url": "https://files.pythonhosted.org/packages/d4/2b/5be8ff6f6475321d1dfc3e6d09b301481e8560425edc5fce7c0c2447185c/codex_usage_monitor-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-27 08:28:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Coldsewoo",
"github_project": "codex-usage-monitor",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "codex-usage-monitor"
}
JSON
