Artificial Intelligence Usage

artificial-intelligence-usage analyzes local Codex session rollouts and prints a summary of the latest session followed by daily and per-session prompt, 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.
• Breaks applied prompts down into Normal, Plan, and Goal counts. Goal counts include automatic goal continuations, while background tasks such as guardian reviews are excluded.
• Shows a second table with one row per session, including its start time, finish time, session name (up to 10 characters), first-prompt preview (up to 20 characters), GitHub repository, usage, and language. A session is finished when its final rollout event is task_complete; otherwise its finish value is In progress.
• Reads session names from ~/.codex/session_index.jsonl. Missing names and prompts display as Unknown.
• For goal-only sessions, reads the goal objective from ~/.codex/goals_1.sqlite for the prompt preview and reports its language as Unknown.
• Uses langid, restricted to English and Spanish, for prompt language detection. Sessions without a detectable user prompt show Unknown.
• 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
• langid 1.1.6 (installed automatically with the package)

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)