https://github.com/blackwell-systems/gcf-kotlin

GCF Kotlin implementation. 100% LLM comprehension on every frontier model. 50-92% fewer tokens than JSON. 43B+ round-trips verified. Zero dependencies.
https://github.com/blackwell-systems/gcf-kotlin

ai-agents android data-serialization decoder encoder gcf graph-compact-format java jitpack json-alternative jvm kotlin llm mcp mcp-tools model-context-protocol structured-data token-efficiency token-optimization wire-format

Last synced: 1 day ago
JSON representation

GCF Kotlin implementation. 100% LLM comprehension on every frontier model. 50-92% fewer tokens than JSON. 43B+ round-trips verified. Zero dependencies.

Host: GitHub
URL: https://github.com/blackwell-systems/gcf-kotlin
Owner: blackwell-systems
License: mit
Created: 2026-06-05T17:51:07.000Z (about 1 month ago)
Default Branch: main
Last Pushed: 2026-06-23T15:25:25.000Z (16 days ago)
Last Synced: 2026-06-23T17:22:23.624Z (16 days ago)
Topics: ai-agents, android, data-serialization, decoder, encoder, gcf, graph-compact-format, java, jitpack, json-alternative, jvm, kotlin, llm, mcp, mcp-tools, model-context-protocol, structured-data, token-efficiency, token-optimization, wire-format
Language: Kotlin
Homepage: https://www.gcformat.com
Size: 1000 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

          


  

  

  



# gcf-kotlin

Kotlin/JVM implementation of [GCF](https://gcformat.com/) -- 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](https://gcformat.com/) · [Playground](https://gcformat.com/playground.html) · [GCF vs TOON](https://gcformat.com/guide/vs-toon.html)

## Install

Add the JitPack repository, then the dependency:

### Gradle (Kotlin DSL)

```kotlin

repositories {

    maven("https://jitpack.io")

}

dependencies {

    implementation("com.github.blackwell-systems:gcf-kotlin:v2.2.1")

}

```

### Gradle (Groovy)

```groovy

repositories {

    maven { url 'https://jitpack.io' }

}

dependencies {

    implementation 'com.github.blackwell-systems:gcf-kotlin:v2.2.1'

}

```

### Maven

```xml

    

        jitpack.io

        https://jitpack.io

    

    com.github.blackwell-systems

    gcf-kotlin

    v2.2.1

```

Don't want to change code? Use the [MCP proxy](https://github.com/blackwell-systems/gcf-proxy) for zero-code adoption.

## Quick Start

```kotlin

import com.blackwellsystems.gcf.*

val output = encodeGeneric(mapOf(

    "employees" to listOf(

        mapOf("id" to 1, "name" to "Alice", "department" to "Engineering", "salary" to 95000),

        mapOf("id" to 2, "name" to "Bob", "department" to "Sales", "salary" to 72000),

    )

))

```

Output:

```

## employees [2]{department,id,name,salary}

Engineering|1|Alice|95000

Sales|2|Bob|72000

```

## Graph Profile

```kotlin

val payload = Payload(

    tool = "context_for_task", tokenBudget = 5000, tokensUsed = 1847,

    symbols = listOf(

        Symbol(qualifiedName = "pkg.Auth", kind = "function", score = 0.78, provenance = "lsp", distance = 0),

        Symbol(qualifiedName = "pkg.Server", kind = "function", score = 0.54, provenance = "lsp", distance = 1),

    ),

    edges = listOf(Edge(source = "pkg.Server", target = "pkg.Auth", edgeType = "calls"))

)

val output = encode(payload)

```

Output:

```

GCF tool=context_for_task budget=5000 tokens=1847 symbols=2 edges=1

## targets

@0 fn pkg.Auth 0.78 lsp

## related

@1 fn pkg.Server 0.54 lsp

## edges [1]

@0<@1 calls

```

## Decode

```kotlin

val p = decode(input)

println("${p.tool} ${p.symbols.size} symbols ${p.edges.size} edges")

```

Throws `DecodeException` on invalid input.

## Session Deduplication

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

```kotlin

val session = Session()

val out1 = encodeWithSession(payload1, session) // full declarations

val out2 = encodeWithSession(payload2, session) // 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:

```kotlin

val enc = StreamEncoder(writer, "context_for_task", StreamOptions(tokenBudget = 5000))

enc.writeSymbol(Symbol(qualifiedName = "pkg.Auth", kind = "function", score = 0.95, provenance = "lsp", distance = 0))

enc.writeEdge(Edge(source = "pkg.Server", target = "pkg.Auth", edgeType = "calls"))

enc.close()  // emits ## _summary trailer

```

Output uses `[?]` deferred counts and `## _summary` trailer. Standard `decode()` handles streaming output with no changes. Thread-safe via `@Synchronized`.

## Delta Encoding

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

```kotlin

val delta = DeltaPayload(

    tool = "context_for_task",

    baseRoot = "aaa111",

    newRoot = "bbb222",

    removed = listOf(Symbol(qualifiedName = "pkg.OldFunc", kind = "function")),

    added = listOf(Symbol(qualifiedName = "pkg.NewFunc", kind = "function", score = 0.85, provenance = "rwr")),

    deltaTokens = 30,

    fullTokens = 200

)

val output = encodeDelta(delta)

```

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

## Generic Encoding

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

```kotlin

val data = mapOf(

    "employees" to listOf(

        mapOf("id" to 1, "name" to "Alice", "department" to "Engineering", "salary" to 95000),

        mapOf("id" to 2, "name" to "Bob", "department" to "Sales", "salary" to 72000),

    )

)

val output = encodeGeneric(data)

```

Output:

```

## employees [2]{department,id,name,salary}

Engineering|1|Alice|95000

Sales|2|Bob|72000

```

Works on maps, lists, and primitives. Arrays of uniform maps get tabular rows. Nested maps use `## key` section headers.

## API

| Function | Description |

|----------|-------------|

| `encode(payload: Payload): String` | Encode a graph payload to GCF text |

| `encodeGeneric(data: Any?): String` | Encode any value to GCF tabular format |

| `decode(input: String): Payload` | Parse GCF text back to a Payload |

| `encodeWithSession(payload: Payload, session: Session?): String` | Encode with session deduplication |

| `encodeDelta(delta: DeltaPayload): String` | Encode a delta (added/removed only) |

| `Session()` | Create a new session tracker (thread-safe) |

## 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 |

| `Session` | Thread-safe tracker for multi-call deduplication |

| `Components` | Score breakdown: blast radius, confidence, recency, distance |

| `DecodeException` | Thrown on invalid GCF input |

| `kindAbbrev` / `kindExpand` | 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](https://github.com/blackwell-systems/toon/tree/gcf-comparison). Full results: [gcformat.com/guide/benchmarks](https://gcformat.com/guide/benchmarks.html)

## Implementations

| Language | Package | Repository |

|----------|---------|-----------|

| Go | `go get github.com/blackwell-systems/gcf-go` | [gcf-go](https://github.com/blackwell-systems/gcf-go) |

| TypeScript | `npm install @blackwell-systems/gcf` | [gcf-typescript](https://github.com/blackwell-systems/gcf-typescript) |

| Python | `pip install gcf-python` | [gcf-python](https://github.com/blackwell-systems/gcf-python) |

| Rust | `cargo add gcf` | [gcf-rust](https://github.com/blackwell-systems/gcf-rust) |

| Swift | Swift Package Manager | [gcf-swift](https://github.com/blackwell-systems/gcf-swift) |

| Kotlin | JitPack | [gcf-kotlin](https://github.com/blackwell-systems/gcf-kotlin) |

| MCP Proxy | `pip install gcf-proxy` | [gcf-proxy](https://github.com/blackwell-systems/gcf-proxy) (bidirectional, session dedup, HTTP frontend) |

| Claude Code Plugin | `/plugin install` | [gcf-claude-plugin](https://github.com/blackwell-systems/gcf-claude-plugin) (one-command install, session stats hook) |

| Codex Plugin | `codex plugin add` | [gcf-codex-plugin](https://github.com/blackwell-systems/gcf-codex-plugin) (one-command install, session stats hook) |

| VS Code | `ext install blackwell-systems.gcf-vscode` | [gcf-vscode](https://marketplace.visualstudio.com/items?itemName=blackwell-systems.gcf-vscode) (syntax highlighting) |

| n8n | `npm install n8n-nodes-gcf` | [gcf-n8n-nodes](https://github.com/blackwell-systems/gcf-n8n-nodes) (workflow encode/decode) |

| Tree-sitter | `npm install tree-sitter-gcf` | [tree-sitter-gcf](https://github.com/blackwell-systems/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](https://github.com/blackwell-systems/gcf/blob/main/SPEC.md) 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.

## License

MIT - [Dayna Blackwell](https://github.com/blackwell-systems)

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/blackwell-systems/gcf-kotlin

Awesome Lists containing this project

README