Skip to main content

kuzystats

What a Codex or Claude Code session is running on, and how many tokens it has used.

Give kuzystats a session's UUID or its name, and it reports the model, the reasoning effort, the working directory, token and cache counts and the last recorded error, as JSON. It reads the files that Codex and Claude Code already keep on your machine; it needs no service, account or network access.

It is part of kuzys, a suite of tools for long-lived AI agents.

What it is for

When several agents run on one machine, you often need a quick, factual answer about one of them: which model is it on, with what effort, in which directory, and how much has it used? kuzystats answers with one command, by name:

$ kuzystats ada --pretty
{
  "backend": "codex",
  "effort": "xhigh",
  "model": "gpt-5.6-sol",
  "model_observed_at": "2026-07-26T18:44:12Z",
  "ok": true,
  "session_id": "0f0f0f0f-0000-4000-8000-000000000003",
  "session_name": "ada",
  "title": "Refactor the config parser",
  "usage": {
    "cached_input_tokens": 700,
    "input_tokens": 1000,
    "output_tokens": 200,
    "reasoning_output_tokens": 50,
    "scope": "session_total",
    "total_tokens": 1200,
    ...
  },
  "workdir": "/home/ada/projects/site",
  ...
}

kuzystats looks at one session at a time. For how much of an account's usage window is left, see its sibling kuzyquota.

What is included

One command, kuzystats. It works on its own: it does not need kuzywrap or any other kuzys service.

Install

Choose one method; do not install Python packages into the system Python with pip. Source-build instructions and the Python/native boundary are documented in Distribution packaging.

Python / PyPI

Use Python 3.11 or newer with virtual-environment support, without sudo:

python3 -m venv ~/.venvs/kuzystats
. ~/.venvs/kuzystats/bin/activate
python -m pip install 'kuzystats'

This installs the kuzystats command and its Python modules. Runtime state and accounts used by the report are external; installation does not create them.

Debian 13 / APT

Configure the kuzys APT repository using Get started, then install on Debian 13 (trixie), amd64:

sudo apt install kuzystats

Fedora 45 / RPM

Configure the kuzys RPM repository using its repository and signing-key instructions. The coordinated release targets Fedora 45 on x86_64, from the kuzys testing repository. Once the repository and the package release are available:

sudo dnf install kuzystats

First steps

Ask by UUID, or by the name the session has in Codex or Claude Code:

kuzystats 0f0f0f0f-0000-4000-8000-000000000003 --pretty
kuzystats ada --pretty

Names are matched exactly, ignoring case. For Codex, kuzystats uses the thread names in ~/.codex/session_index.jsonl. For Claude Code, it uses the session's custom title or its generated slug. If the same name exists in both tools, choose one with --backend:

kuzystats ada --backend codex
kuzystats ada --backend claude

Without --pretty the JSON is printed on one line. Errors are JSON too, with a non-zero exit status: for example session_not_found, or ambiguous_session when a name matches more than one session.

kuzystats reads ~/.codex and ~/.claude by default. To read other directories, export these variables before running it:

export KUZYSTATS_CODEX_HOME=/path/to/codex-home
export KUZYSTATS_CLAUDE_HOME=/path/to/claude-home

If they are not set, kuzystats falls back to the older names SESSION_MODEL_CODEX_HOME and SESSION_MODEL_CLAUDE_HOME, then to CODEX_HOME and CLAUDE_CONFIG_DIR.

What the numbers mean

Token counts are what the runtime itself recorded. They are not invoices.

  • Codex reports running totals in its latest token_count event. Its input_tokens already includes cached input: do not add cached_input_tokens to it.
  • Claude Code keeps no running total for a session. kuzystats adds up the usage of each distinct assistant message in the transcript. For Claude, total_input_tokens is uncached input plus cache creation plus cache reads.
  • A recorded rate-limit error is history. Compare its time with model_observed_at before you treat it as current.
  • The transcripts do not contain provider quota or billing weights. Use the totals to see which session used what, not as exact costs.

Development

python3 -m venv .venv
.venv/bin/pip install -e '.[test]'
.venv/bin/python -m pytest -q

Status and limits

  • Version 0.1.1, early. The JSON carries "schema_version": "kuzystats.v1", but the fields may still change.
  • kuzystats reads files that Codex and Claude Code write for their own use. They are not public interfaces and can change with a new release of either tool.
  • Tested on Linux only.

License

AGPL-3.0-or-later. See LICENSE.

Distribution packaging

See Distribution packaging for the common build commands, the Python/native boundary and external dependencies.

Metadata

Release files for kuzystats 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kuzystats 0.1.1
File Size Uploaded Provenance Actions
kuzystats-0.1.1.tar.gz 28.9 kB Without provenance Details for kuzystats-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kuzystats 0.1.1
File Interpreter ABI Platform Actions
kuzystats-0.1.1-py3-none-any.whl Python 3 none any Details for kuzystats-0.1.1-py3-none-any.whl

Total release size: 50.7 kB

Release files / kuzystats-0.1.1.tar.gz

Download URL kuzystats-0.1.1.tar.gz
Size 28.9 kB
Tags Source
SHA-256 checksum
How to use checksums
1073b6ead2032f7f8ba60facebfa0aefea95688e090fbdcaa7aa1978a2ecadec
BLAKE2b-256 checksum
How to use checksums
924a2483d3c13d608ad58819a0d3a3ff25ba95990f3616d7d942576b869b69fb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Release files / kuzystats-0.1.1-py3-none-any.whl

Download URL kuzystats-0.1.1-py3-none-any.whl
Size 21.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
72a0937ebe9a7ced95dec11e7d011dd90be777c5aba27a5566b2524b405c4e38
BLAKE2b-256 checksum
How to use checksums
f103fb4e3dedec5a7e1693ccee510684ed5213eeda6ec87c0b131457cf10dee9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Security for kuzystats 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page