@blackwell-systems/gcf

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.

100% comprehension on every frontier model tested. 29% fewer tokens than TOON, 56% fewer than JSON across 16 datasets. 91.2% on structurally complex code graphs (vs TOON 68.8%, JSON 54.1%). 2,400+ LLM evaluations. Zero training.

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: 92.7% token savings vs JSON.

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,400+ LLM evaluations across 10 models, 3 providers, and 51 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.2 Stable with 174 conformance fixtures, 43,000,000,000+ lossless round-trips verified across 5 formats and 6 languages. All implementations at v2.2.1+ (Go v1.3.1). Cross-language 6x6 matrix verified.

Adopted by

Chrome DevTools MCP (46K stars, Google Chrome DevTools team) · Speakeasy (API tooling, customers include Google, Verizon, Mistral AI, DocuSign, Vercel) · OmniRoute (6.1K stars) · NetClaw (556 stars) · ctx (510 stars) · NeuroNest · Open Data Products SDK (Linux Foundation) · Raycast · and more

License

MIT - Dayna Blackwell