CLI tool to track OpenAI Codex usage with multi-account support

Project description

codex-usage

CLI tool to track OpenAI Codex usage with multi-account support and automatic account cycling.

Features

Usage Tracking: Check 5-hour and weekly usage limits for Codex CLI accounts
Multi-Account Management: Add, switch, remove, and list multiple Codex accounts
Automatic Cycling: Automatically switch accounts when usage limits are exhausted
Multiple Output Formats: Table, JSON, and compact oneline formats
Caching: 5-minute cache to reduce API calls

Installation

macOS

# Using Homebrew (coming soon)
brew install Liam-Deacon/tap/codex-usage

Linux

# Download from releases
curl -L https://github.com/Liam-Deacon/codex-usage/releases/latest/download/codex-usage-x86_64-unknown-linux-gnu -o codex-usage
chmod +x codex-usage
sudo mv codex-usage /usr/local/bin/

Windows

# Using Scoop (coming soon)
scoop bucket add Liam-Deacon https://github.com/Liam-Deacon/scoop-bucket
scoop install codex-usage

Python (uvx)

uvx codex-usage --help

Docker

docker pull ghcr.io/liam-deacon/codex-usage:latest
docker run --rm ghcr.io/liam-deacon/codex-usage:latest --help

Build from Source

cargo build --release
sudo cp target/release/codex-usage /usr/local/bin/

Quick Start

Login to Codex (if not already):
```
codex login
```
Add your account:
```
codex-usage accounts add myaccount
```
Check usage:
```
codex-usage status
```

Usage

Check Usage

# Check active account usage
codex-usage status

# Check all connected accounts
codex-usage status --all

# Output as JSON
codex-usage status --json

# Compact oneline output
codex-usage status --oneline

# Force refresh (skip cache)
codex-usage status --refresh

Account Management

# List all connected accounts
codex-usage accounts list

# Add current Codex auth as new account
codex-usage accounts add myaccount

# Switch to another account
codex-usage accounts switch myaccount

# Switch with force (override safety check)
codex-usage accounts switch myaccount --force

# Remove an account
codex-usage accounts remove myaccount

Automatic Cycling

Configure automatic account switching when usage limits are exhausted:

# Show cycle status
codex-usage cycle status

# Configure thresholds
codex-usage cycle config --five-hour 0 --weekly 10 --mode or

# Enable cycling
codex-usage cycle enable

# Disable cycling
codex-usage cycle disable

# Manually trigger cycle check
codex-usage cycle now

# View cycle history
codex-usage cycle history

# Reorder accounts in cycle
codex-usage cycle reorder account1 account2 account3

Wakeup

Trigger Codex to utilize daily/weekly limits:

# Run wakeup now
codex-usage wakeup --run

# Run wakeup for specific account
codex-usage wakeup --run --account myaccount

# Force wake even if Codex is running
codex-usage wakeup --run --force

# Install wakeup schedule (e.g., daily at 8am and 2pm)
codex-usage wakeup install --at 08:00 --at 14:00

# Install with interval between --at times
codex-usage wakeup install --at 08:00 --interval 1h

# List current wakeup schedules
codex-usage wakeup list

# Remove wakeup schedule
codex-usage wakeup remove

# Attempt to wake system from sleep (macOS)
codex-usage wakeup --run --wake-system

Watch

Continuously monitor usage with live updates:

# Watch active account (default 10s interval)
codex-usage watch

# Watch with custom interval
codex-usage watch --interval 30s

# Watch all accounts
codex-usage watch --all

# Force refresh on each poll (skip cache)
codex-usage watch --refresh

History

Track and analyze usage over time:

# Manage background recording daemon
codex-usage history daemon start --interval 5m
codex-usage history daemon stop
codex-usage history daemon status

# Show usage history
codex-usage history show
codex-usage history show --period week
codex-usage history show --from 2025-01-01 --to 2025-01-31
codex-usage history show --account myaccount

# Show terminal bar chart
codex-usage history chart
codex-usage history chart account1 account2

# Show allowance analysis
codex-usage history allowance
codex-usage history allowance --projected
codex-usage history allowance --dead-time

# Configure notifications
codex-usage history notify --enable
codex-usage history notify --disable
codex-usage history notify --hours-before 2
codex-usage history notify --status

# Export history data
codex-usage history export
codex-usage history export --output usage.json
codex-usage history export --period month --format json

Configuration

Config Directory

Default: ~/.codex-usage/

Override with:

codex-usage --config-dir /path/to/config status

Or set environment variable:

export CODEX_USAGE_DIR=/path/to/config

Files

config.json - Main configuration
accounts/ - Stored account auth files
cycle.json - Cycle configuration
cycle_history.jsonl - Cycle history
usage_cache.json - Usage data cache
wakeup.json - Wakeup configuration

Environment Variables

Variable	Description
`CODEX_USAGE_DIR`	Override config directory
`CODEX_USAGE_VERBOSE`	Enable verbose logging

License

MIT License - see LICENSE file.

Project details

Release history Release notifications | RSS feed

0.1.19

Feb 16, 2026

0.1.18

Feb 16, 2026

0.1.17

Feb 16, 2026

0.1.16

Feb 16, 2026

0.1.15

Feb 16, 2026

0.1.14

Feb 16, 2026

0.1.13

Feb 16, 2026

0.1.12

Feb 16, 2026

0.1.11

Feb 16, 2026

0.1.10

Feb 16, 2026

0.1.8

Feb 15, 2026

This version

0.1.7

Feb 15, 2026

0.1.6

Feb 15, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

codex_usage-0.1.7.tar.gz (69.9 kB view details)

Uploaded Feb 15, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

codex_usage-0.1.7-cp38-abi3-win_amd64.whl (2.6 MB view details)

Uploaded Feb 15, 2026 CPython 3.8+Windows x86-64

codex_usage-0.1.7-cp38-abi3-manylinux_2_39_x86_64.whl (2.9 MB view details)

Uploaded Feb 15, 2026 CPython 3.8+manylinux: glibc 2.39+ x86-64

codex_usage-0.1.7-cp38-abi3-macosx_11_0_arm64.whl (2.5 MB view details)

Uploaded Feb 15, 2026 CPython 3.8+macOS 11.0+ ARM64

codex_usage-0.1.7-cp38-abi3-macosx_10_12_x86_64.whl (2.7 MB view details)

Uploaded Feb 15, 2026 CPython 3.8+macOS 10.12+ x86-64

File details

Details for the file codex_usage-0.1.7.tar.gz.

File metadata

Download URL: codex_usage-0.1.7.tar.gz
Upload date: Feb 15, 2026
Size: 69.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for codex_usage-0.1.7.tar.gz
Algorithm	Hash digest
SHA256	`d10559c4f14a8b7fe0b6ee03386109606d3df5c61208fdddd8cd30f3b7a32ec7`
MD5	`189fd47d07fdc9ce17efb71a3ac6743d`
BLAKE2b-256	`f648e6abf7522c0fc6397a4c4788dd0006e2f4807404557e814bdf1046666c86`

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_usage-0.1.7.tar.gz:

Publisher: pypi.yaml on Liam-Deacon/codex-usage

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: codex_usage-0.1.7.tar.gz
- Subject digest: d10559c4f14a8b7fe0b6ee03386109606d3df5c61208fdddd8cd30f3b7a32ec7
- Sigstore transparency entry: 953493009
- Sigstore integration time: Feb 15, 2026
Source repository:
- Permalink: Liam-Deacon/codex-usage@c3c478f65356e4f9cdfbcfa56d890a24425d5618
- Branch / Tag: refs/tags/v0.1.7
- Owner: https://github.com/Liam-Deacon
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: pypi.yaml@c3c478f65356e4f9cdfbcfa56d890a24425d5618
- Trigger Event: workflow_dispatch

File details

Details for the file codex_usage-0.1.7-cp38-abi3-win_amd64.whl.

File metadata

Download URL: codex_usage-0.1.7-cp38-abi3-win_amd64.whl
Upload date: Feb 15, 2026
Size: 2.6 MB
Tags: CPython 3.8+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for codex_usage-0.1.7-cp38-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`3a4e58474452ca951d56d1c14aae2d27ba62bbc5294fefa6689cf52c81632661`
MD5	`db745b6380cbbbffe9494bb0eaeb5757`
BLAKE2b-256	`98fbd04f9f84318b4506c1060ee5bda0a7a0a18136b54ffc677ed60b1836b64a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_usage-0.1.7-cp38-abi3-win_amd64.whl:

Publisher: pypi.yaml on Liam-Deacon/codex-usage

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: codex_usage-0.1.7-cp38-abi3-win_amd64.whl
- Subject digest: 3a4e58474452ca951d56d1c14aae2d27ba62bbc5294fefa6689cf52c81632661
- Sigstore transparency entry: 953493011
- Sigstore integration time: Feb 15, 2026
Source repository:
- Permalink: Liam-Deacon/codex-usage@c3c478f65356e4f9cdfbcfa56d890a24425d5618
- Branch / Tag: refs/tags/v0.1.7
- Owner: https://github.com/Liam-Deacon
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: pypi.yaml@c3c478f65356e4f9cdfbcfa56d890a24425d5618
- Trigger Event: workflow_dispatch

File details

Details for the file codex_usage-0.1.7-cp38-abi3-manylinux_2_39_x86_64.whl.

File metadata

Download URL: codex_usage-0.1.7-cp38-abi3-manylinux_2_39_x86_64.whl
Upload date: Feb 15, 2026
Size: 2.9 MB
Tags: CPython 3.8+, manylinux: glibc 2.39+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for codex_usage-0.1.7-cp38-abi3-manylinux_2_39_x86_64.whl
Algorithm	Hash digest
SHA256	`710f2b77265e1f61344baf23dbd5802fa0c37468af5d8d95cb92612d587b9dad`
MD5	`431930368ee571c1067a80a752d96b6f`
BLAKE2b-256	`0c3a4320b92187cd900810cc479fc1395b8afb66cb131579c8f784ca89433f51`

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_usage-0.1.7-cp38-abi3-manylinux_2_39_x86_64.whl:

Publisher: pypi.yaml on Liam-Deacon/codex-usage

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: codex_usage-0.1.7-cp38-abi3-manylinux_2_39_x86_64.whl
- Subject digest: 710f2b77265e1f61344baf23dbd5802fa0c37468af5d8d95cb92612d587b9dad
- Sigstore transparency entry: 953493016
- Sigstore integration time: Feb 15, 2026
Source repository:
- Permalink: Liam-Deacon/codex-usage@c3c478f65356e4f9cdfbcfa56d890a24425d5618
- Branch / Tag: refs/tags/v0.1.7
- Owner: https://github.com/Liam-Deacon
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: pypi.yaml@c3c478f65356e4f9cdfbcfa56d890a24425d5618
- Trigger Event: workflow_dispatch

File details

Details for the file codex_usage-0.1.7-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: codex_usage-0.1.7-cp38-abi3-macosx_11_0_arm64.whl
Upload date: Feb 15, 2026
Size: 2.5 MB
Tags: CPython 3.8+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for codex_usage-0.1.7-cp38-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`dea777c3fb4ac32ab6a55c932cfffb3d3c1ae590dc4572f4501829ff9fbe2ce3`
MD5	`d61e05002aae88d9be620b276cc6e28b`
BLAKE2b-256	`98e68da04c2dc11d74063082a7538bb21ff1185b4f4685e80f1f473aa2e60c67`

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_usage-0.1.7-cp38-abi3-macosx_11_0_arm64.whl:

Publisher: pypi.yaml on Liam-Deacon/codex-usage

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: codex_usage-0.1.7-cp38-abi3-macosx_11_0_arm64.whl
- Subject digest: dea777c3fb4ac32ab6a55c932cfffb3d3c1ae590dc4572f4501829ff9fbe2ce3
- Sigstore transparency entry: 953493013
- Sigstore integration time: Feb 15, 2026
Source repository:
- Permalink: Liam-Deacon/codex-usage@c3c478f65356e4f9cdfbcfa56d890a24425d5618
- Branch / Tag: refs/tags/v0.1.7
- Owner: https://github.com/Liam-Deacon
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: pypi.yaml@c3c478f65356e4f9cdfbcfa56d890a24425d5618
- Trigger Event: workflow_dispatch

File details

Details for the file codex_usage-0.1.7-cp38-abi3-macosx_10_12_x86_64.whl.

File metadata

Download URL: codex_usage-0.1.7-cp38-abi3-macosx_10_12_x86_64.whl
Upload date: Feb 15, 2026
Size: 2.7 MB
Tags: CPython 3.8+, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for codex_usage-0.1.7-cp38-abi3-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`18e65e800f1cd6ffae5b1eca6ec2ce6895ef09a528fec559dd141b58095e9f27`
MD5	`8828808e0190543f7bc26624eae3a298`
BLAKE2b-256	`eb2d07aa22d5cb73afb4de86c756db07802811f5e6700dac924a9e440fe275da`

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_usage-0.1.7-cp38-abi3-macosx_10_12_x86_64.whl:

Publisher: pypi.yaml on Liam-Deacon/codex-usage

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: codex_usage-0.1.7-cp38-abi3-macosx_10_12_x86_64.whl
- Subject digest: 18e65e800f1cd6ffae5b1eca6ec2ce6895ef09a528fec559dd141b58095e9f27
- Sigstore transparency entry: 953493014
- Sigstore integration time: Feb 15, 2026
Source repository:
- Permalink: Liam-Deacon/codex-usage@c3c478f65356e4f9cdfbcfa56d890a24425d5618
- Branch / Tag: refs/tags/v0.1.7
- Owner: https://github.com/Liam-Deacon
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: pypi.yaml@c3c478f65356e4f9cdfbcfa56d890a24425d5618
- Trigger Event: workflow_dispatch

codex-usage 0.1.7

Navigation

Verified details

Maintainers

Unverified details

Meta

Project description

codex-usage

Features

Installation

macOS

Linux

Windows

Python (uvx)

Docker

Build from Source

Quick Start

Usage

Check Usage

Account Management

Automatic Cycling

Wakeup

Watch

History

Configuration

Config Directory

Files

Environment Variables

License

Related

Project details

Verified details

Maintainers

Unverified details

Meta

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance