TECHDEV · Open-source tool

jsonfold

Paste a 40 KB API response into a chat and a surprising share of the tokens are just key names repeated on every object: stargazers_count, stargazers_count, stargazers_count… jsonfold renames long keys to $0, $1, … — ordered by bytes saved, so the most expensive keys get the shortest aliases — and leaves everything else alone. The output is still plain, readable JSON. A map file remembers the renaming, and unfold restores the original byte-for-byte.

View on GitHub →Read the article →

Node.js 18+ · Zero dependencies · MIT

The receipt, every run

Every fold run does an internal round-trip check (fold → unfold → deep-equal) before writing anything, and prints a receipt to stderr:

jsonfold receipt
  original:  3,760 bytes
  folded:    2,940 bytes
  saved:     820 bytes (21.8%)
  est. tokens saved: ~205 (~4 chars/token heuristic)
  keys aliased: 27 (of 29 unique, 133 occurrences)
  alias prefix: "$"
  round-trip: OK (fold→unfold→deep-equal)

Those are real numbers from the bundled demo (examples/repo-list.json, an invented 3.8 KB repo-list payload that ships minified — so the 21.8% is pure key-aliasing, no whitespace trickery).

Receipt format copied exactly from the jsonfold README ("What jsonfold does").

Quick start

# No dependencies. Node >= 18.
git clone https://github.com/techdevfun/jsonfold.git
cd jsonfold
node bin/jsonfold.js --help

# 1. Fold. Writes folded.json + folded.json.map, prints the receipt to stderr.
node bin/jsonfold.js fold api.json -o folded.json

# 2. Paste folded.json into your prompt. Keep the .map file on your machine.

# 3. Unfold the model's output back to the original keys.
node bin/jsonfold.js unfold folded.json --map folded.json.map -o restored.json

Pipes work too — the receipt goes to stderr, never stdout:

cat api.json | node bin/jsonfold.js fold > folded.json

Not sure it's worth it? Ask first — stats shows byte counts, key counts, the top-10 keys by byte contribution, an estimated token count, and the projected savings, without writing anything:

node bin/jsonfold.js stats api.json
node bin/jsonfold.js stats api.json --json   # stats as JSON

# indented output, machine-readable receipt
node bin/jsonfold.js fold api.json --pretty -o folded.json
node bin/jsonfold.js fold api.json --receipt receipt.json

Commands copied exactly from the jsonfold README ("Install" + "Usage in three steps"). Exit codes: 0 success · 1 invalid JSON / unreadable file / bad map / round-trip check failed · 2 usage error.

The `$0` problem, handled

If your JSON already contains keys shaped like $0, $1, … a naive aliaser would create ambiguity on unfold. jsonfold detects this, switches the alias prefix to the first safe candidate (#, @, ~, §), and records the switch in the map file. Unfolding needs no extra flags.

From the jsonfold README ("The $0 problem, handled").

Honest comparison

Tool	What it does	What it doesn't do
`jq -c`	Minifies whitespace; full query language for JSON.	Can't shorten keys. No savings estimate, no receipt.
`jsonpack` (npm, MIT)	Dictionary-encodes repeated keys and values into base-36 indices; output is a flat ASCII string for URLs / localStorage. Reversible with `unpack`.	Output is not readable JSON — you can't inspect or hand-edit it in a prompt. No receipt, no token estimate. Built for storage/transport, not prompts.
Lossy "AI compressors" / summarizers	Rewrite or drop content to save tokens.	Not reversible. You can't verify what changed.
jsonfold	Aliases keys only; output stays valid, readable JSON; reversible via a map file; every run prints a verifiable receipt and passes an internal round-trip check.	Doesn't touch values, doesn't dedupe strings, doesn't minify beyond key shortening. Token counts are a heuristic, not a tokenizer measurement.

Prior-art note from the README (2026-10-21): a quick check of the npm registry and the web found the jsonfold name free and no zero-dependency CLI doing reversible key-aliasing with a printed, verifiable savings receipt. jsonpack is the closest reversible tool, but it targets a different job (opaque transport encoding). If you know of closer prior art, open an issue on the repo.

Comparison table copied from the jsonfold README ("Honest comparison").

Limits

Not a lossy summarizer. It never drops, reorders, or rewrites fields.
Doesn't touch values. Numbers, strings, and unicode survive the round-trip byte-identical. Only object keys are renamed.
Not a general compressor. Values aren't interned or encoded; if your payload's bulk is in long string values rather than repeated keys, stats will tell you folding isn't worth it.
Token numbers are estimates. The ~4 chars/token figure is a rough heuristic, labeled everywhere it appears. It is not a measurement from any specific model's tokenizer.

Limits from the jsonfold README's own notes ("What jsonfold is not").

Roadmap — not shipped yet

Publish to npm (npx jsonfold).
--only / --ignore key filters for payloads where some keys must stay readable.
Benchmarks against jsonpack and gzip on standard corpora, published with methodology.
A man page.

Out of scope by design: lossy modes, value interning, network calls of any kind. This tool reads JSON and writes JSON, nothing else.

Roadmap copied from the jsonfold README; none of these have shipped yet (2026-10-30).

License

MIT — see LICENSE in the repository.

Have a say

Vote for this tool, suggest a feature, or discuss it with other operators on the community board.