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_countevent. Itsinput_tokensalready includes cached input: do not addcached_input_tokensto 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_tokensis uncached input plus cache creation plus cache reads. - A recorded rate-limit error is history. Compare its time with
model_observed_atbefore 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.