generic-ml-wrapper 0.10.0

A metering wrapper around your ML coding CLI

Run claude, cursor, codex, or vibe exactly as you know them — but on a job you tag, in a named, resumable session, with every turn's tokens and cost recorded. An application that uses an ML client, not an ML client pretending to be an application.

Why a wrapper  •  Clients  •  The job  •  Install  •  Workflows  •  What it records  •  Concepts  •  Guides  •  Design

Why a wrapper

The raw coding CLIs are black boxes. A session has no name you chose, so you can't find it again. A run's cost is invisible — you never learn what a task actually spent. The exact context a session launched with is gone the moment it starts. And every client does all of this differently, so nothing you learn about one transfers to the next.

gmlw is a thin, deterministic shell around the client that keeps the client's behaviour intact and adds the parts an application needs:

• Identity — you enter at a job you tag; the wrapper mints a named, resumable session on the client.
• Metering — a local relay sits between the client and its upstream API and records tokens and cost per turn, for any metered client, without changing a single thing about how the client runs.
• Provenance — the compiled context a session launched with is written to disk; opt in to a full transcript and every call's request, response, and usage is kept too.
• One surface — claude, cursor, codex, and vibe are all driven the same way and land in the same ledger.

The judgment stays in the client. The deterministic parts — session identity, launch, context compilation, persistence, metering — are Python you can read.

Clients at a glance

Four clients, one surface — but they are not identical. What each supports today:

¹ Codex resumes from its first completed turn onward: it mints its own session id, which the wrapper binds off the wire rather than handing it one at launch.

Cursor isn't metered by the open-source wrapper (its usage isn't on an interceptable API); Vibe doesn't resume. See docs/CLIENTS.md for the per-client detail and setup.

The job

A job is the one concept everything hangs off. It's the piece of work you're tagging — a ticket, a refactor, an investigation — and it is the primary key of the whole ledger.

job  ──►  sessions  ──►  turns ──► tokens + cost
                    └───► context.md (what it launched with)
                    └───► transcript (opt-in: in / out / usage per call)

You start work at a job and read it back by job:

gmlw start REFACTOR-42                 # mint + launch a session on the default client
gmlw start REFACTOR-42 --resume-latest # pick the latest session back up
gmlw jobs                              # every job with recorded activity
gmlw sessions REFACTOR-42              # that job's sessions, oldest first
gmlw export REFACTOR-42                # per-turn tokens + cost, totalled by model

Nothing about the client changes — you get its full TUI. The wrapper owns the identity, the launch, and the persistence around it.

Install

Requires one supported coding CLI already installed and logged in (claude, cursor-agent, codex, or vibe). The console script is gmlw.

Linux / macOS:

curl -LsSf https://raw.githubusercontent.com/danielslobozian/generic-ml-wrapper/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/danielslobozian/generic-ml-wrapper/main/install.ps1 | iex

Each script ensures uv is present — installing it first if not — then runs uv tool install generic-ml-wrapper. No Python prerequisite: uv fetches its own interpreter. Already have uv?

uv tool install generic-ml-wrapper     # or: uv sync --extra dev  (from a clone)

Either way:

gmlw start MY-FIRST-JOB                # first run self-seeds ~/.gmlw (owner-only)

On first run the wrapper creates ~/.gmlw/ (mode 0700) with a commented config.toml, a SQLite ledger, and the workflow, profile, environment and template folders. Pick the client per run with --client claude|cursor|codex|vibe, or set a default in config.toml.

Update

gmlw does not update itself. It checks PyPI at most once a day (cached, and only if [update] check is on — the default) and notes a newer version on the exit receipt when one exists; nothing is downloaded or installed on your behalf. To update:

uv tool upgrade generic-ml-wrapper     # or: uv tool install --reinstall generic-ml-wrapper

Workflows

A workflow is a small operating context you author once and launch a job with. Rather than re-explaining the same standing instructions to the client every time, you compile them once — a base, your profile, the rules of your environment and role, and the workflow's own steps — into the context the session opens with.

gmlw workflow new doc-review           # author a workflow (an authoring session, kept apart from work)
gmlw workflow list                     # the runnable workflows
gmlw start DOCS-1 --workflow doc-review # launch a job with that context compiled in

Workflows can carry their own credentials (gmlw creds set <workflow> <ENV_VAR>), injected into the child process at launch and stored 0600. Context compilation runs through an interceptor chain, so a step like context compression is an opt-in plug-in, not a fork of the engine.

What it records

Everything lives under ~/.gmlw/, owner-only, on your machine:

For Claude Code and Cursor, the wrapper renders a rich status line straight into the client's own status bar — the git branch, folder, model, context %, and live cost, plus the job's running total. (The status-line seam is client-agnostic; Claude and Cursor are wired today, and other parsers can be added.)

Your operating context, carried across clients

Beyond metering, gmlw builds a portable operating context that follows you from one client to the next — who you are, your project's conventions, a learned notebook, a selectable persona, and rules you've demanded be held to — composed from four independent axes and packaged per launch mode. See docs/CONCEPTS.md for the full model.

Workflows (above) are optional and separate from this personal layer. Every listing/reporting command also speaks --json for automation.

What gmlw does not do

• It is not a sandbox — it launches the real client with your credentials (see SECURITY.md).
• It does not meter Cursor, and does not resume Vibe (see the matrix).
• It does not call models itself — the optional context compressor records through generic-ml-cache.
• It ships no compression prompts — the compressor stays inert until you configure one.

Guides

See docs/README.md for the full map. Start with Concepts for the mental model, then the User guide for task-oriented recipes, or jump straight to the CLI reference · Configuration · Clients · Workflows · Troubleshooting · Design · Security · Contributing.

Develop

The gates are defined once in noxfile.py; CI is a thin caller of them, so what runs locally is byte-for-byte what runs in CI.

uv sync --extra dev          # or: nox -s dev   (builds the IDE .venv)
nox                          # lint · imports · typecheck · tests (3.11–3.14)
nox -s green                 # the whole gate in one env (lint · format · imports · pyright · coverage)

Strict ruff + pyright (over src and tests), import-linter hexagon contracts, and an 80% coverage floor all run in the gate. Every change goes on a branch (feature/… tech/… fix/… docs/… chore/… test/…), keeps nox -s green passing, and merges via PR — direct pushes to main are blocked by branch protection.

See docs/DESIGN.md for the architecture, SECURITY.md for the threat model, and CONTRIBUTING.md to get set up.

Family

Part of the generic-ml-* family, alongside generic-ml-cache (record/replay execution cache — the wrapper's context compressor records through it) and generic-ml-workflow.

License

Apache-2.0 — see LICENSE and NOTICE. Contributions welcome; see CONTRIBUTING.md.