# costcut

> The token-reduction layer for AI-agent context. Compresses tool output and
> large reads (JSON, diffs, grep, file reads) before they reach the model, and
> keeps the full original in a durable local store so any elided region is
> recoverable byte-for-byte via a handle. Pure-Python, local-first, no ML, no
> network. MIT.

Key idea: lossy in the prompt, lossless in the store. Each compact rendering
carries a `costcut get <handle>` pointer to the original — the agent never has
to re-run a command to recover what was elided.

## Surfaces
- Library: `from cost_guard.compress import compress, retrieve`
- CLI: `costcut wrap -- <cmd>`, `costcut get <handle>`, `costcut gc`, `costcut bench`
- Proxy: a Claude Code PreToolUse hook (`costcut init`) auto-wraps lossy reads
- MCP server: tools `costcut_compress`, `costcut_retrieve`, `costcut_stats`

## Reproducible metrics
Run `costcut bench` (neutral `o200k_base` tokenizer, asserts byte-identical
round-trip). Flagship: JSON state dump 6055→466 tokens (92.3% reduction),
lossless via store. Structural grep/diff are conservative pure-Python defaults.

## Docs
- Docs site: https://docs.costcut.dev
- PyPI: https://pypi.org/project/costcut/
- Full agent context: /llms-full.txt