Artificial Intelligence Usage

artificial-intelligence-usage analyzes local Codex session rollouts and prints a summary of the latest session followed by daily session, turn, token, and rate-limit usage.

Behavior

• Reads rollout files below ~/.codex/sessions.
• Shows the installed Codex and Claude CLI versions when those commands are available.
• Shows status details from the most recently modified session.
• Reports sessions from the last 14 calendar days by default, including today.
• Counts user turns and cumulative tokens for each session.
• Shows the remaining five-hour and weekly allowance recorded in each day's last session.
• Ignores malformed JSON lines and incomplete status events.

The tool only reads local session files and does not modify them.

Requirements

• Python 3.10 or newer

Building

Testing

Run the unit tests from the project root:

python3 -m unittest discover -s tests -v

Package artifact

Build and validate the package artifacts:

./build-package.sh

This creates the wheel and source distribution under dist/ and checks the package metadata with Twine.

Publish artifact

Publish the generated artifacts to PyPI:

./publish-pypi.sh

The publish script checks that Twine is available, creates a local .venv for Twine when needed, verifies that dist/ contains generated artifacts, and then uploads them. If PyPI rejects a version that was already published, increment the version in pyproject.toml, rebuild, and publish again.

Install artifact

Install the package in a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install artificial-intelligence-usage

Usage

After installation, run:

artificial-intelligence-usage

Choose a different reporting window with --days:

artificial-intelligence-usage --days 30

From a source checkout, ./artificial-intelligence-usage.py is the canonical launcher and ./script-sessions.py remains available for compatibility.

Help

usage: artificial-intelligence-usage [-h] [--days DAYS]

Analyze recent Codex sessions.

options:
  -h, --help   show this help message and exit
  --days DAYS  number of calendar days to analyze, including today (default: 14)