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.

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

When the consumer already has a prior context pack, send only what changed:

import { encodeDelta, type DeltaPayload } from '@blackwell-systems/gcf';

const delta: DeltaPayload = {
  tool: 'context_for_task',
  baseRoot: 'aaa111',
  newRoot: 'bbb222',
  removed: [{ qualifiedName: 'pkg.OldFunc', kind: 'function', score: 0, provenance: '', distance: 0 }],
  added: [{ qualifiedName: 'pkg.NewFunc', kind: 'function', score: 0.85, provenance: 'rwr', distance: 0 }],
  removedEdges: [],
  addedEdges: [],
  deltaTokens: 30,
  fullTokens: 200,
};

const output = encodeDelta(delta);

81.2% savings on re-queries where the pack changed slightly.

Generic Encoding

Encode any JS value (not just graph payloads) into GCF tabular format:

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

Works on objects, arrays, and primitives. Arrays of uniform objects get tabular rows. Nested objects use ## key section headers.

Generic-Profile Delta (multi-turn)

In an agent loop the same keyed table gets re-queried turn after turn. Instead of re-sending the whole table each time, send only the changed rows (SPEC §10a):

import {
  diffGenericSets,
  encodeGenericDelta,
  verifyGenericDelta,
  type GenericSet,
} from '@blackwell-systems/gcf';

const base: GenericSet = {
  key: 'id',
  fields: ['id', 'status'],
  rows: [
    { id: 1001, status: 'pending' },
    { id: 1002, status: 'shipped' },
  ],
};
const next: GenericSet = {
  key: 'id',
  fields: ['id', 'status'],
  rows: [
    { id: 1001, status: 'shipped' }, // changed
    { id: 1003, status: 'pending' }, // added (1002 removed)
  ],
};

const d = diffGenericSets(base, next);          // GenericDeltaPayload
const wire = encodeGenericDelta(d);             // ## added / ## changed / ## removed
const held = verifyGenericDelta(base, d, d.newRoot); // atomic apply + new_root verification

Opt-in and bilateral, keyed on content-addressed pack roots. By the 5th overlapping call, ~97% fewer tokens than re-sending JSON.

Re-anchor session helper

GenericDeltaSession manages the delta/re-anchor cadence for you: each next() returns either a compact delta or, on its cadence, a full re-anchor (which re-grounds the consumer), updating its held base.

import { GenericDeltaSession, sizeGuard } from '@blackwell-systems/gcf';

const sess = new GenericDeltaSession(base, 'orders', sizeGuard());
let wire = sess.currentFull();                  // transmit the base once to establish it
for (const snapshot of stream) {                // each turn's current GenericSet
  const { wire, isFull } = sess.next(snapshot); // a compact delta, or a periodic full re-anchor
}

fixedN(15) re-anchors every N turns; sizeGuard() (recommended) re-anchors once the cumulative delta reaches a full payload's size. It introduces no new wire syntax and the decoder stays cadence-agnostic, so a re-anchor is just the protocol's "full" outcome on a schedule.

API

| Function | Description | |----------|-------------| | encode(p: Payload): string | Encode a graph payload to GCF text | | encodeGeneric(data: unknown): string | Encode any value to GCF tabular format | | decode(input: string): Payload | Parse GCF text back to a Payload | | encodeWithSession(p: Payload, s: Session): string | Encode with session deduplication | | new StreamEncoder(w, tool, opts) | Create a streaming encoder (zero-buffering) | | encodeDelta(d: DeltaPayload): string | Encode a delta (added/removed only) | | diffGenericSets(base, next): GenericDeltaPayload | Diff two keyed record sets (generic profile) | | encodeGenericDelta(d): string / decodeGenericDelta(s) | Generic-profile delta wire (§10a) | | verifyGenericDelta(base, d, root): GenericSet | Atomic apply + new_root verification | | new GenericDeltaSession(base, tool, policy) | Producer-side re-anchor cadence helper (§10a.8) | | new Session() | Create a new session tracker |

Types

| Type | Purpose | |------|---------| | Payload | Full GCF payload: tool, budget, symbols, edges, pack root | | Symbol | Graph node: qualified name, kind, score, provenance, distance | | Edge | Directed relationship: source, target, edge type | | DeltaPayload | Diff between two packs: added/removed symbols and edges | | GenericSet / GenericDeltaPayload | Keyed record set and its generic-profile diff (§10a) | | GenericDeltaSession | Stateful producer that schedules delta vs full re-anchor (§10a.8) | | Session | Tracker for multi-call deduplication | | KIND_ABBREV / KIND_EXPAND | Bidirectional kind abbreviation maps |

Benchmarks

2,500+ LLM evaluations across 11 models, 4 providers, and 50+ independent test runs.

| | GCF | TOON | JSON | |---|---|---|---| | Comprehension (23 runs, 10 models) | 91.2% | 68.8% | 54.1% | | Generation (28 runs, 9 models) | 5/5 | 1.0/5 | 5.0/5 | | Input tokens (500 symbols) | 11,090 | 16,378 | 53,341 | | Output tokens (100 symbols) | 5,976 | 8,937 | 16,121 |

GCF wins 15/16 datasets on the expanded token efficiency benchmark. Full results: gcformat.com/guide/benchmarks

Implementations

| Language | Package | Repository | |----------|---------|-----------| | Go | go get github.com/blackwell-systems/gcf-go | gcf-go | | TypeScript | npm install @blackwell-systems/gcf | gcf-typescript | | Python | pip install gcf-python | gcf-python | | Rust | cargo add gcf | gcf-rust | | Swift | Swift Package Manager | gcf-swift | | Kotlin | JitPack | gcf-kotlin | | MCP Proxy | pip install gcf-proxy | gcf-proxy (bidirectional, session dedup, HTTP frontend) | | Claude Code Plugin | /plugin install | gcf-claude-plugin (one-command install, session stats hook) | | Codex Plugin | codex plugin add | gcf-codex-plugin (one-command install, session stats hook) | | VS Code | ext install blackwell-systems.gcf-vscode | gcf-vscode (syntax highlighting) | | n8n | npm install n8n-nodes-gcf | gcf-n8n-nodes (workflow encode/decode) | | Tree-sitter | npm install tree-sitter-gcf | tree-sitter-gcf |

Zero runtime dependencies. Permanently. All six implementations depend only on their language's standard library. No transitive dependencies. No supply chain risk. This is a permanent commitment: GCF will never take on external runtime dependencies. MIT licensed. All implementations support both generic profile (encodeGeneric) and graph profile (encode). CLI included in all 6 languages.

Specification: SPEC v3.5.3 Stable with 279 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. Current versions: Go v1.7.0, TypeScript v2.6.0, Python v2.6.0, Rust v3.0.0, Swift v2.7.0, Kotlin v2.6.0, .NET v0.2.0. Cross-language conformance verified across all seven SDKs.

Adopted by

| Project | | |---------|--| | Chrome DevTools MCP | 47K★ · the Google Chrome DevTools team's MCP server; exposes live browser state (DOM, network, console, performance) to AI coding agents | | Speakeasy | OpenAPI tooling (customers include Google, Verizon, Mistral AI, DocuSign, Vercel); GCF is a native output format in their oq CLI | | OmniRoute | 17K★ · AI gateway, registry, and proxy between AI clients and model providers; GCF vendored into its compression engine | | NetClaw | 610★ · AI-powered network automation (113 skills, 66 MCP integrations); replaced TOON with GCF across every MCP server | | ctx | 552★ · real-time context selector for Claude Code; surfaces only the relevant tools from a 103K-node knowledge graph | | Lynkr | 531★ · local LLM gateway for AI coding clients; GCF as a drop-in tool-result compressor alongside TOON | | Open Data Products SDK | Linux Foundation · Python toolkit and MCP server for data-product standards; GCF sidecars for agent context | | NeuroNest | agent-first IDE; first commercial GCF adoption, across four encoding surfaces with session dedup and delta | | Raycast | JSON-to-GCF Converter extension in the Raycast Store, for the macOS productivity launcher |

See all adopters →

License

MIT - Dayna Blackwell