@blackwell-systems/gcf weekly downloads statistics

<p align="center"> <a href="https://gcformat.com/playground.html"><img src="https://img.shields.io/badge/playground-live-2563eb?style=for-the-badge" alt="Playground"></a> <a href="https://gcformat.com/guide/benchmarks.html"><img src="https://img.shields.io/badge/benchmarks-2%2C500%2B%20evals-22c55e?style=for-the-badge" alt="Benchmarks"></a> <a href="https://www.npmjs.com/package/@blackwell-systems/gcf"><img src="https://img.shields.io/npm/v/@blackwell-systems/gcf?style=for-the-badge&logo=npm&logoColor=white&color=cb3837" alt="npm"></a> <a href="https://github.com/blackwell-systems/gcf-typescript/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-333?style=for-the-badge" alt="License"></a> </p> <p align="center"> <img src="https://raw.githubusercontent.com/blackwell-systems/gcf-typescript/main/assets/gcf-hero-wire-delta.png" alt="gcf-typescript" width="760"> </p>

gcf-typescript

TypeScript implementation of GCF, the most token-efficient wire format for LLMs. A drop-in alternative to JSON and TOON for any structured data.

<p align="center"> <img src="https://raw.githubusercontent.com/blackwell-systems/gcf-typescript/main/assets/divider-wave-2.png" alt="" width="100%"> </p> <p align="center"> <img src="https://raw.githubusercontent.com/blackwell-systems/gcf-typescript/main/assets/gcf-ts-diagram.png" alt="gcf-typescript" width="80%"> </p> <p align="center"> <img src="https://raw.githubusercontent.com/blackwell-systems/gcf-typescript/main/assets/divider.png" alt="" width="100%"> </p>

Built for the agentic loop, where the same structured context crosses the model boundary turn after turn. A single payload is 50-92% smaller than JSON, but GCF also deduplicates repeated structure across turns and sends only deltas when context changes, so by the 5th overlapping call each response costs 99% fewer tokens than JSON, and a 10-call session runs 94.4% cheaper than re-sending JSON every turn. Session dedup and delta both need local IDs and a multi-turn design that neither JSON nor TOON has.

• 100% comprehension on every frontier model, zero training. 29% fewer tokens than TOON and 56% fewer than JSON across 16 datasets; 91.2% on structurally complex code graphs (vs TOON 68.8%, JSON 54.1%).
• Proven lossless across 43,000,000,000+ round-trips in 5 formats and 6 languages. Zero runtime dependencies.
• One format, four properties no other single format holds at once: schema-free, lossless, token-compact (50-92% vs JSON), and model-readable with zero training. JSON is verbose, Protobuf needs a schema, MessagePack is binary, and TOON isn't reliably lossless.

2,500+ LLM evaluations. Full benchmarks.

Docs: gcformat.com · Playground · GCF vs TOON

Install

npm install @blackwell-systems/gcf

Zero dependencies. TypeScript-first. Includes CLI. Don't want to change code? Use the MCP proxy for zero-code adoption.

CLI

npx @blackwell-systems/gcf encode < payload.json    # JSON to GCF
npx @blackwell-systems/gcf decode < payload.gcf     # GCF to JSON
npx @blackwell-systems/gcf stats  < payload.json    # token comparison

Payload: 50 symbols, 20 edges

  JSON  ██████████████████████████████  4,200 tokens
  GCF   ████████░░░░░░░░░░░░░░░░░░░░░░  1,150 tokens

  Savings: 73% fewer tokens with GCF

Or install globally: npm install -g @blackwell-systems/gcf then use gcf directly.

Library

Quick Start

import { encodeGeneric } from '@blackwell-systems/gcf';

const output = encodeGeneric({
  employees: [
    { id: 1, name: 'Alice', department: 'Engineering', salary: 95000 },
    { id: 2, name: 'Bob', department: 'Sales', salary: 72000 },
  ],
});

Output:

## employees [2]{id,name,department,salary}
1|Alice|Engineering|95000
2|Bob|Sales|72000

Decode

import { decode } from '@blackwell-systems/gcf';

const p = decode(input);
console.log(p.tool, p.symbols.length, 'symbols', p.edges.length, 'edges');

Session Deduplication

Track transmitted symbols across multiple tool responses. Previously-sent symbols become bare references instead of full declarations:

import { Session, encodeWithSession } from '@blackwell-systems/gcf';

const sess = new Session();

const out1 = encodeWithSession(payload1, sess); // full declarations
const out2 = encodeWithSession(payload2, sess); // reused symbols as "@N  # previously transmitted"

By the 5th call in a session: 86% fewer tokens than JSON from dedup alone, 99% stacked with delta encoding.

Streaming Encode

Write GCF output incrementally as symbols and edges arrive. Zero buffering, O(1) memory per row. Ideal for MCP servers that walk large graphs or paginate results:

import { StreamEncoder } from '@blackwell-systems/gcf';

const enc = new StreamEncoder(writer, 'context_for_task', { tokenBudget: 5000 });

// Symbols emit immediately as they're discovered.
enc.writeSymbol({ qualifiedName: 'pkg.Auth', kind: 'function', score: 0.95, provenance: 'lsp', distance: 0 });
enc.writeSymbol({ qualifiedName: 'pkg.Server', kind: 'function', score: 0.60, provenance: 'lsp', distance: 1 });

// Edges emit immediately too.
enc.writeEdge({ source: 'pkg.Server', target: 'pkg.Auth', edgeType: 'calls' });

// Close emits the ##! summary trailer with final counts.
enc.close();

Output:

GCF tool=context_for_task budget=5000
## targets
@0 fn pkg.Auth 0.95 lsp
## related
@1 fn pkg.Server 0.60 lsp
## edges [?]
@0<@1 calls
##! summary symbols=2 edges=1 counts=1,1,1

The writer is any object with a write(s: string) method (Node.js streams, web WritableStreams, or a simple callback). Standard decode() handles streaming output with no changes.

Delta Encoding…