The token-reduction layer for AI-agent context.
Compress tool output and large reads before they hit the model — and expand any elided region back to the byte-identical original on demand. Lossy in the prompt, lossless in the store.
100% free · MIT licensed · no accounts, no limits, no payments
92.3% on JSON · library · CLI · proxy · MCP · local-first · no ML
pip install costcut
# wrap any read-only command — get a compact view + a handle
costcut wrap --kind json -- cat big_state.json
costcut get <handle> # expand back, byte-identical
costcut get <handle> --lines 40-80 # or just a sliceLong homogeneous arrays are sampled, huge scalar strings truncated — whitespace stripped. The flagship case.
Diff hunks and grep matches are headed-and-summarised, with the full
body one costcut get away.
Large reads and git logs collapse to a head plus a retrievable pointer; code files can use a signature view.
Small outputs pass through verbatim — there is nothing worth eliding, and no store entry is created.
compress() / retrieve()
wrap · get · gc · bench
costcut init
costcut_compress …
Measured by costcut bench with the neutral
o200k_base tokenizer — and every row round-trips
byte-identically. Run it yourself; the numbers are the product's own.
| Input | Tokens raw → compact | Reduction | Restore |
|---|---|---|---|
| JSON state dump (60 records) | 6055 → 466 | 92.3% | byte-identical |
| ripgrep match dump | 3080 → 1728 | 43.9% | byte-identical |
| multi-file git diff | 5948 → 4922 | 17.2% | byte-identical |
Structural diff/grep defaults are conservative — they keep more context and are not tuned to flatter the corpus.
Every compact rendering names a handle and the exact command to recover the rest:
--- CTXTEE json cut=54items handle=33d6f94 get="costcut get 33d6f94" ---
The full original lives in a local SQLite store (~/.costcut,
durable 7 days). Retrieve the whole thing or a precise slice — a line
range, one file's matches, a single diff hunk, or a symbol body — many
turns later, with no re-run. No data ever leaves your machine.