Metadata-Version: 2.4
Name: codex-usage-tracking
Version: 0.27.0
Summary: Fast, exact, local-first Codex usage facts and evidence.
Author: Douglas Monsky
License-Expression: MIT
Project-URL: Homepage, https://github.com/douglasmonsky/codex-usage-tracker
Project-URL: Repository, https://github.com/douglasmonsky/codex-usage-tracker
Project-URL: Issues, https://github.com/douglasmonsky/codex-usage-tracker/issues
Keywords: codex,tokens,usage,local-first
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pyright>=1.1.405; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
Requires-Dist: xenon>=0.9.3; extra == "dev"
Dynamic: license-file

# Codex Usage Tracker

Codex Usage Tracker is a fast, local-first data kernel for exact Codex usage
facts and evidence. Version 0.27 adds compact guided exploration and optional,
owner-only context composition to the 0.26 incremental kernel while preserving
bounded queries, exact evidence timelines, the six-tool MCP surface, and the
focused Evidence Console.

- Product roadmap: `docs/roadmap/product-kernel-reset.md`
- Execution ledger: `docs/roadmap/product-kernel-reset-execution.md`
- Active search policy: `docs/kernel-development-scope.md`
- Optional context composition: `docs/kernel-context-composition.md`
- Read-only overlay adapter contract: `docs/kernel-overlay-adapter-contract.md`
- Frozen code disposition: `config/kernel-code-disposition-v1.json`
- Frozen retired surfaces: `config/kernel-retired-surfaces-v1.json`

Run the repository verification gate with:

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
just v
```

The previous 0.25.1 implementation remains available at the immutable
`v0.25.1` tag. Do not restore retired analysis, telemetry, compatibility, or
static-dashboard runtime modules into the active tree.

## Install

Install the Python runtime into an isolated executable environment, then add
the same tagged repository as a Codex plugin marketplace:

```bash
pipx install "codex-usage-tracking==0.27.0"
codex plugin marketplace add douglasmonsky/codex-usage-tracker --ref v0.27.0
codex plugin add codex-usage-tracker@codex-usage-tracker
```

The plugin launches the `codex-usage-tracker` executable, so the MCP process
uses the exact interpreter owned by the pipx installation. After install,
start a fresh Codex task so its tool catalog is discovered from the new
plugin bundle.
