Metadata-Version: 2.4
Name: tokki
Version: 1.0.0
Summary: Token killer for local developer sessions.
Author: Jean-Pierre Morard
Maintainer: Jean-Pierre Morard
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/jpmorard/tokki-public
Project-URL: Repository, https://github.com/jpmorard/tokki-public
Project-URL: Issues, https://github.com/jpmorard/tokki-public/issues
Project-URL: Documentation, https://github.com/jpmorard/tokki-public#readme
Keywords: compiled-wheel,developer-tools,proprietary,tokki
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Tokki

<p align="center">
  <img
    src="https://raw.githubusercontent.com/jpmorard/tokki-public/main/docs/assets/tokki-logo.jpg"
    alt="Tokki logo"
    width="720"
  >
</p>

[![Distribution: Private wheelhouse](https://img.shields.io/badge/Distribution-Private%20wheelhouse-blue.svg)](wheelhouse/tokki-1.0.0)
[![License: Proprietary](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE)

Tokki is a proprietary local developer tool distributed as compiled wheels.
It is a token killer for local developer sessions: built to cut avoidable local
agent context before it becomes prompt spend, while keeping implementation
details and local payloads private.

This public package and repository contain limited package information, license
terms, public proof figures, and security-contact guidance only.
Implementation source and detailed operational documentation are private.

## Public Report

Proof figures from the maintainer checkout (2026-06-05, local metadata only;
summary-only public evidence):

| Signal | Figure | Public evidence boundary |
|---|---:|---|
| Current-session demo | 99.0% avoidable context removed | summary-only local ledger; no prompts, raw logs, paths, or file bodies |
| Current-session net result | 4,233,059 tokens kept local | aggregate public proof, no per-event details |
| Repeatable benchmark pack | 80,485 net tokens saved | tokenizer-counted benchmark bundle; source hidden |
| Dirty-worktree context | 80,263 baseline -> 136 Tokki tokens, 590x | source-hidden repository context benchmark |
| Cost projection | $8.218 projected avoided | default demo prices; not billing evidence |
| Privacy guard | 0 strict findings | public-surface privacy scan passed |

This is a public teaser, not an operational manual. Detailed mechanisms,
commands, source paths, raw logs, and private reports stay out of this
repository.

## Tokki and Caveman Code

Caveman Code is the agent choice: a full terminal coding agent whose token
strategy is to keep its own replies terse and enforce tight tool-output budgets.

Tokki is the wrapper choice: a source-private, compiled local layer that keeps
your existing agent commands and reduces avoidable local context before it
becomes prompt spend. Public Tokki evidence remains summary-only: no prompts,
raw logs, file bodies, source paths, or implementation details.

Use Caveman Code when you want the agent itself to be the frugal surface. Use
Tokki when you want a private compiled-wheel layer around the agents you already
use. The two can complement each other: Tokki can install wrappers with
`tokki setup` without making the Tokki source public.

The private CLI also includes `tokki benchmark` for comparing report-path
timings. Its log-digest benchmark path uses the native Rust helper when
available and falls back to Python only for compatibility, while public
evidence stays summary-only.

## Install

Tokki ships as compiled wheels staged in this private repo under
`wheelhouse/tokki-1.0.0/`. Install the wheel matching your OS, then verify with
`tokki --version` and `tokki doctor --strict`. PyPI publishing is retired.
Checksums are stored beside the wheels in `SHA256SUMS`.

Private maintainers with access to this source repository can install directly
from a fresh clone when Rust/Cargo is installed:

```sh
uv tool install --force "git+https://github.com/jpmorard/tokki.git"
tokki --version
```

For a local checkout or venv:

```sh
git clone https://github.com/jpmorard/tokki.git
cd tokki
python3 -m pip install .
tokki --version
```

This private source-install path builds `protected-rust` during wheel creation
when `dist-protected/tokki` is missing. It is for the private repository only;
do not mirror it into `tokki-public` or the public installers unless explicitly
doing public installer/docs work.

<p align="center">
  <img
    src="https://raw.githubusercontent.com/jpmorard/tokki-public/main/docs/assets/tokki-deployment-flow.png"
    alt="Tokki deployment flow"
    width="860"
  >
</p>

After install, the non-destructive first-run check is:

```sh
tokki proof
tokki smoke
tokki privacy explain
```

To install available wrappers and run the same trust/adoption proof in one
flow:

```sh
tokki setup --guided
```

### macOS

Apple Silicon wheel:

```sh
python3 -m pip install --user --upgrade --force-reinstall \
  wheelhouse/tokki-1.0.0/tokki-1.0.0-py3-none-macosx_11_0_arm64.whl
export PATH="$HOME/Library/Python/3.*/bin:$HOME/.local/bin:$PATH"
tokki --version
```

Optional isolated install with `uv`:

```sh
uv tool install --force \
  wheelhouse/tokki-1.0.0/tokki-1.0.0-py3-none-macosx_11_0_arm64.whl
tokki --version
```

Install wrappers after the wheel is installed:

```sh
tokki setup --guided
```

Uninstall:

```sh
python3 -m pip uninstall -y tokki
uv tool uninstall tokki 2>/dev/null || true
```

### Linux

x86_64 wheel:

```sh
python3 -m pip install --user --upgrade --force-reinstall \
  wheelhouse/tokki-1.0.0/tokki-1.0.0-py3-none-manylinux_2_35_x86_64.whl
export PATH="$HOME/.local/bin:$PATH"
tokki --version
```

Optional isolated install with `pipx`:

```sh
python3 -m pipx install --force \
  wheelhouse/tokki-1.0.0/tokki-1.0.0-py3-none-manylinux_2_35_x86_64.whl
tokki --version
```

Install wrappers after the wheel is installed:

```sh
tokki setup --guided
```

Uninstall:

```sh
python3 -m pip uninstall -y tokki
python3 -m pipx uninstall tokki 2>/dev/null || true
```

### Agent Wrappers On POSIX

After install, run `tokki setup` to install wrappers and check the health of the
local wrapper path. For `codex`, the health report also compares the installed
CLI version against the latest published `@openai/codex` version when both can
be parsed as real semver tokens; otherwise the version stays unknown and Tokki
does not claim an upgrade.

Tokki does not silently replace one agent command with another by default, and
it does not auto-use a standalone local LLM just because `ollama` or another
CLI is installed. Cross-agent low-tier handoff, for example launching Codex or
a local backend from a simple Claude one-shot prompt, is opt-in. The installer
can write a small `install.env` config that sets `TOKKI_MODEL_LOW_AGENT`,
`TOKKI_MODEL_ALLOW_CROSS_AGENT_HANDOFF`, and optionally
`TOKKI_MODEL_LOW_HANDOFF_MODEL`; env vars still override that file. Set the
agent to `codex` to route to the latest GPT mini model, `claude` to stay on
Claude with the canonical low-model preset `claude-3-5-haiku-latest`, or
`ollama` with an explicit model name. Set the agent to `local` with
`TOKKI_MODEL_LOW_HANDOFF_COMMAND` and optional `TOKKI_MODEL_LOW_HANDOFF_ARGS` to
use another local model CLI instead of Ollama. The local backend is considered
only when `TOKKI_MODEL_LOW_AGENT=ollama` or `TOKKI_MODEL_LOW_AGENT=local`,
`TOKKI_MODEL_ALLOW_CROSS_AGENT_HANDOFF=1`, model routing selects the low tier,
and the wrapped Claude command is a simple one-shot prompt; interactive sessions
and unsupported flag combinations stay on Claude. Claude handoff model aliases
are allowlisted; stale or invalid aliases fall back to
`claude-3-5-haiku-latest` and are recorded as metadata-only invalid config
events.

Tokki also honors `TOKKI_TOKEN_SAVING_MODE=aggressive`,
`TOKKI_TOKEN_SAVING_MODE=ultimate`, or `TOKKI_TOKEN_SAVING_MODE=emergency`.
Weekly-hours quota signals can escalate the mode automatically: `25%` remaining
switches to `aggressive`, `10%` to `ultimate`, and `5%` to `emergency`. The
lower modes reduce the compact-response budget, compact-trigger threshold, and
native output budgets more aggressively than the default mode. When
output overflows, Tokki emits a terse local handle receipt and keeps the full
payload recoverable with `tokki retrieve <handle>`.

### Windows

x86_64 PowerShell wheel:

```powershell
py -m pip install --user --upgrade --force-reinstall `
  wheelhouse\tokki-1.0.0\tokki-1.0.0-py3-none-win_amd64.whl
tokki --version
```

Optional isolated install with `pipx`:

```powershell
py -m pip install --user pipx
py -m pipx ensurepath
pipx install --force `
  wheelhouse\tokki-1.0.0\tokki-1.0.0-py3-none-win_amd64.whl
tokki --version
```

Install wrappers after the wheel is installed:

```powershell
tokki setup --guided
```

Uninstall:

```powershell
py -m pip uninstall -y tokki
pipx uninstall tokki
```

Windows notes:

- The core CLI (`tokki run`, `fix`, `map`, `query`, `model-route`, ...) works
  natively in PowerShell and cmd.
- The installer and `tokki setup` install native `.exe` agent wrappers in the
  same PATH directory as `tokki.exe` when supported agent commands are present.
  Use `-NoWrappers` or `TOKKI_NO_WRAPPERS=1` for a core-CLI-only install. POSIX
  shell shims remain the Unix/WSL path.
- Tokki stores its runtime config under `%APPDATA%\tokki\runtime.json` and
  logs/reports under `%LOCALAPPDATA%\tokki\`. Set `TOKKI_RUNTIME_CONFIG`,
  `TOKKI_LOG_DIR`, or `TOKKI_REPORT_DIR` to override.

## Public Package

Current public package: `tokki 1.0.0`.

`1.0.0` provides private wheelhouse artifacts for:

- macOS arm64: `tokki-1.0.0-py3-none-macosx_11_0_arm64.whl`
- Linux x86_64: `tokki-1.0.0-py3-none-manylinux_2_35_x86_64.whl`
- Windows x86_64: `tokki-1.0.0-py3-none-win_amd64.whl`

The wheel intentionally does not include private implementation source,
repository-local tests, protected Rust source, or private development scripts.

## Support

Use GitHub issues for installation problems and public package metadata issues.
For failure reports, prefer `tokki issue report` so Tokki can send a bounded,
privacy-filtered digest with the issue. Use `tokki issue fix` to read a
`tokki-auto` issue back into a local fix bundle. Do not post secrets, prompts, command output,
private repository contents, or customer material in public issues. The
`tokki-auto` label should stay restricted to trusted triage users so untrusted
reporters cannot publish into the fix queue.

For a local trust summary before filing anything public, run
`tokki privacy explain`. It describes what Tokki stores locally, what public
reports omit, and which audit commands to run before sharing artifacts.

For installation or wrapper issues, run `tokki install doctor` first. Use
`tokki path doctor` / `tokki path repair` for PATH drift, `tokki installer-parity`
and `tokki installer-matrix` to compare POSIX, Windows, uv, pipx, and user-site
installer contracts across the private/public surfaces, and `tokki conformance`
for the composed local suite. `tokki release evidence --output tokki-evidence.json`
and `tokki release evidence verify --manifest tokki-evidence.json` write and
verify metadata-only release provenance. `tokki support-bundle --output
tokki-support.json` writes a metadata-only diagnostic bundle for support.
