Metadata-Version: 2.4
Name: kuzystats
Version: 0.1.1
Summary: Inspect native Codex and Claude Code session statistics.
Author-email: Michele Renda <michele.renda@protonmail.com>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://gitlab.com/kuzys/kuzystats
Project-URL: Issues, https://gitlab.com/kuzys/kuzystats/-/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Dynamic: license-file

# 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](https://www.kuzys.com), 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:

```console
$ 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](https://gitlab.com/kuzys/kuzyquota).

## What is included

One command, `kuzystats`. It works on its own: it does not need
[kuzywrap](https://gitlab.com/kuzys/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](docs/DISTRIBUTION_PACKAGING.md).

### Python / PyPI

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

```sh
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](https://www.kuzys.com/install.html),
then install on Debian 13 (trixie), amd64:

```sh
sudo apt install kuzystats
```

### Fedora 45 / RPM

Configure the [kuzys RPM repository](https://rpm.kuzys.com/) 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:

```sh
sudo dnf install kuzystats
```

## First steps

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

```sh
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`:

```sh
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:

```sh
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

```sh
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](LICENSE).

## Distribution packaging

See [Distribution packaging](docs/DISTRIBUTION_PACKAGING.md) for the common
build commands, the Python/native boundary and external dependencies.
