Quickstart

What to download

Nothing, in the usual sense. uvx fetches and runs the audit in one step, in an isolated environment it cleans up itself. If you prefer a persistent install:

$ uvx coldworks-audit --help          # run without installing
$ uv tool install coldworks-audit     # or keep it on your PATH

See it work before you export anything

Empty-handed? The package writes a sample span export itself, so the first report costs you nothing but the command:

$ uvx coldworks-audit run --sample --open

This renders the full report — headline, repeat groups, nondeterminism findings, loss populations — on data we wrote, labeled as such on every screen. The release-1 sample is span-only; documents arrive with --docs in release 2.

Your first real audit

1. Export traces from wherever they live — takes about 30 seconds. See Connect your traces for the Langfuse, LangSmith, and OpenTelemetry paths.
2. Run the audit on the file:

$ uvx coldworks-audit run ~/Downloads/traces.jsonl --open

3. Read the headline. The share of your agent's context that sits in exact repeats of a judgment it already made — in your own tool vocabulary. Repeats count as cache candidates only when their results agree; disagreeing repeats are reported separately as nondeterminism findings. The report opens with one sentence: “This report is the first step of an audit, not a dashboard. Where your platform already prints this number, start from that number; what this adds is the groups that disagree and the populations it could not read.”

If the audit can't read your export

It doesn't report a silent zero. It prints a field census — "your spans carry tool names but not structured arguments" — so even a failed audit hands you a concrete, forwardable finding about your own telemetry.

Where to go next

• Connect your traces — the per-source paths, and how to make the audit standing instead of one-off.
• The audit CLI — every flag, and the exact list of what never leaves your machine.