- Table form — repeated field names collapse to a header; rows become positional.
- Dictionary form — repeated values become short back-references to a legend.
- Cross-call diffs — when a tool returns something similar to last time, terse sends only the provable delta.
- Field offload — a huge value becomes a handle you fetch back exactly on demand, so it stops eating context until you need it.
Case study · AI infrastructure
Cutting agent token cost without losing a byte
Agent tool outputs are quietly one of the most expensive things in an AI stack. terse is a drop-in proxy that losslessly compresses that output — 58% fewer tokens on a real corpus — while keeping every single piece of information.
The hidden cost
Every search result, directory listing, and API response comes back as repetitive JSON — the same field names on every row, the same values over and over, padding everywhere. The model re-reads that bloat on every turn. Multiply it by every tool call, every turn, every session, and repetitive tool output becomes a line item you pay on continuously.
Why the usual fixes are the wrong trade
- Summarize or truncate — lossy. You lose data and can no longer trust the result for anything correctness-sensitive.
- Buy a bigger context window — you still pay per token; a longer window doesn't make the bloat cheaper, it just delays the ceiling.
terse refuses the trade. Its one unbreakable rule: the compressed output can always be turned back into the exact original. If a payload ever couldn't round-trip perfectly, terse treats that as a failure and sends the original — not as an acceptable trade-off. Lossless is the default, not a mode.
How it shrinks things
$ cat tool-output.json | terse gate -
round-trip lossless: PASS
cl100k tokens: 1810 -> 881 (51.3% saved)It is selective and honest: output that's already tidy is passed through untouched rather than churned for a rounding-error gain. A one-time primer — paid once per session, not per result — teaches the model to read the dense encoding directly, so there's no decoding step in your own code.
Measured against TOON
The honest way to state a compression claim is against something else that already exists. TOON is a published token-oriented serialisation format with the same goal, so the benchmark runs both over the same nine real GitHub API payloads — 365,144 raw tokens, every row verified lossless, counted in the same tokenizer.
| Payload | Raw tokens | terse | TOON |
|---|---|---|---|
| gh_workflow_runs | 76,032 | 80.3% | −7.5% |
| gh_pulls | 151,165 | 76.1% | −8.4% |
| gh_issues | 48,032 | 32.7% | −8.0% |
| gh_dir_listing | 6,736 | 31.4% | −7.7% |
| gh_commits | 69,652 | 26.5% | −4.5% |
| gh_labels | 632 | 15.2% | 19.0% |
| gh_rate_limit | 357 | 13.4% | −36.7% |
| gh_repo_single | 1,652 | 0.0% | −4.4% |
| Weighted total | 365,144 | 58.3% | −7.1% |
Percentages are fewer tokens than the raw JSON, so a negative number means the encoding
made the payload bigger. TOON regresses on nested records because it adds a
key-path at every level of nesting; terse folds the repeated subtrees instead — the
gh_pulls row is sixty copies of the same repository object collapsed to one
legend entry.
TOON wins one row, and it is left in. gh_labels is a flat table of short
uniform values, which is precisely what TOON was designed for. A benchmark that only
reports the rows you win is not a benchmark.
Re-run on 29 July 2026 and unchanged from the published figures: the corpus is pinned and
the encoder version is locked, so the number is reproducible rather than remembered.
uv run scripts/bench/benchmark.py in the repository reproduces this table.
Built to be invisible and safe
- Fail-open. If any compression goes wrong, terse forwards the original result. A tool call is never lost.
- Self-verifying. A diff is only sent when it provably reconstructs the result; the full form is always the fallback.
- Bounded. The compression logic is pure and testable; in-flight tracking is capped so a flaky server can't leak memory.
From the outside, nothing changes except that token usage drops.
Who this is for
If you run MCP servers, agent harnesses, or anything that pipes large tool outputs into an LLM on a loop, terse removes over half of that cost with a guarantee that nothing is ever lost.
AI Infra
Developer Tooling
Python
MCP
uv tool install terse-mcp # or: pipx install terse-mcp
terse proxy -- uvx some-mcp-server --flagsQuestions or a use case in mind? Email is best — [email protected] · Back to portfolio