feat: add gcf output format

[blackwell-systems]

Adds gcf as an output format alongside toon, json, yaml, md, and jsonl. One branch in Formatter.format(), mirroring the existing TOON path. Opt-in via --format gcf; TOON stays the default and is untouched.

Why

TOON re-declares a nested object's schema on every row, so on nested tool/API responses it can encode larger than raw JSON. GCF path-flattens nested fields, so it ties TOON on flat records and is materially smaller on nested ones, while round-tripping losslessly.

Benchmark (40-record nested API response — the shape incur-wrapped OpenAPI/MCP tools return; o200k, GCF round-trip verified lossless):

format	tokens
JSON	3548
TOON (current default)	4288
GCF	2453

GCF is −30.9% vs JSON and −42.8% vs TOON; TOON runs +20.9% larger than JSON on nested payloads. On flat uniform records GCF ties TOON (both ~30% below JSON).

Comprehension (the part that matters for an agent framework)

The tokens saved don't cost the agent any accuracy. On a generic-profile comprehension eval — 500 orders with nested customer objects and line items, 13 structured-extraction questions, zero format instructions, deterministic answers (no LLM judge), 27 runs across 11 models — GCF scores 100% on every frontier model (Claude Opus/Sonnet/Haiku 4.x, GPT-5.5, Gemini 2.5 Pro / 3.x) and leads on smaller models (Gemini 2.5 Flash: GCF 95.0% vs TOON 85.1% vs JSON 74.0%; Mistral Medium 3.5: GCF 82.7% vs TOON 76.9%). That workload — arrays of objects with nested metadata — is exactly what a CLI-wrapped tool response looks like. Agents read GCF at least as accurately as JSON, and more accurately than TOON where accuracy is scarce. Full data: https://gcformat.com/guide/benchmarks

Correctness

GCF round-trips losslessly by design. For contrast, a 100k-case fuzz of the reference @toon-format/toon shows a 7.47% round-trip failure rate (1.73% of it silent, no error thrown), reproducible via eval/toon-fuzz.mjs. @blackwell-systems/gcf is MIT with zero runtime dependencies.

In production elsewhere

GCF ships as an opt-in format in Chrome DevTools MCP, is vendored into OmniRoute's compression engine, replaced TOON in NetClaw, and was merged into Speakeasy's oq. Full list: gcformat.com/ecosystem/adopters.

Format + research

Spec and playground at gcformat.com (vs-TOON, benchmarks); the format and its underlying tokenizer/attention research are documented in the whitepaper (DOI 10.5281/zenodo.20579817).

Additive and opt-in; happy to adjust naming, placement, or scope to fit the project's conventions.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​blackwell-systems/​gcf@​2.4.0

View full report