{"id":51508551,"url":"https://github.com/blackwell-systems/gcf-kotlin","last_synced_at":"2026-07-08T03:30:39.666Z","repository":{"id":362750715,"uuid":"1260635241","full_name":"blackwell-systems/gcf-kotlin","owner":"blackwell-systems","description":"GCF Kotlin implementation. 100% LLM comprehension on every frontier model. 50-92% fewer tokens than JSON. 43B+ round-trips verified. Zero dependencies.","archived":false,"fork":false,"pushed_at":"2026-06-23T15:25:25.000Z","size":1028,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T17:22:23.624Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://www.gcformat.com","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blackwell-systems.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["blackwell-systems"]}},"created_at":"2026-06-05T17:51:07.000Z","updated_at":"2026-06-23T15:25:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/blackwell-systems/gcf-kotlin","commit_stats":null,"previous_names":["blackwell-systems/gcf-kotlin"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/blackwell-systems/gcf-kotlin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcf-kotlin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcf-kotlin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcf-kotlin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcf-kotlin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blackwell-systems","download_url":"https://codeload.github.com/blackwell-systems/gcf-kotlin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcf-kotlin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35251015,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-07-08T03:30:38.969Z","updated_at":"2026-07-08T03:30:39.652Z","avatar_url":"https://github.com/blackwell-systems.png","language":"Kotlin","funding_links":["https://github.com/sponsors/blackwell-systems"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/blackwell-systems\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/blackwell-systems/blackwell-docs-theme/main/badge-trademark.svg\" alt=\"Blackwell Systems\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/blackwell-systems/gcf-kotlin/actions\"\u003e\u003cimg src=\"https://github.com/blackwell-systems/gcf-kotlin/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# gcf-kotlin\n\nKotlin/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.\n\n**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.**\n\nDocs: [gcformat.com](https://gcformat.com/) · [Playground](https://gcformat.com/playground.html) · [GCF vs TOON](https://gcformat.com/guide/vs-toon.html)\n\n## Install\n\nAdd the JitPack repository, then the dependency:\n\n### Gradle (Kotlin DSL)\n\n```kotlin\nrepositories {\n    maven(\"https://jitpack.io\")\n}\n\ndependencies {\n    implementation(\"com.github.blackwell-systems:gcf-kotlin:v2.2.1\")\n}\n```\n\n### Gradle (Groovy)\n\n```groovy\nrepositories {\n    maven { url 'https://jitpack.io' }\n}\n\ndependencies {\n    implementation 'com.github.blackwell-systems:gcf-kotlin:v2.2.1'\n}\n```\n\n### Maven\n\n```xml\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003ejitpack.io\u003c/id\u003e\n        \u003curl\u003ehttps://jitpack.io\u003c/url\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.blackwell-systems\u003c/groupId\u003e\n    \u003cartifactId\u003egcf-kotlin\u003c/artifactId\u003e\n    \u003cversion\u003ev2.2.1\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nDon't want to change code? Use the [MCP proxy](https://github.com/blackwell-systems/gcf-proxy) for zero-code adoption.\n\n## Quick Start\n\n```kotlin\nimport com.blackwellsystems.gcf.*\n\nval output = encodeGeneric(mapOf(\n    \"employees\" to listOf(\n        mapOf(\"id\" to 1, \"name\" to \"Alice\", \"department\" to \"Engineering\", \"salary\" to 95000),\n        mapOf(\"id\" to 2, \"name\" to \"Bob\", \"department\" to \"Sales\", \"salary\" to 72000),\n    )\n))\n```\n\nOutput:\n```\n## employees [2]{department,id,name,salary}\nEngineering|1|Alice|95000\nSales|2|Bob|72000\n```\n\n## Graph Profile\n\n```kotlin\nval payload = Payload(\n    tool = \"context_for_task\", tokenBudget = 5000, tokensUsed = 1847,\n    symbols = listOf(\n        Symbol(qualifiedName = \"pkg.Auth\", kind = \"function\", score = 0.78, provenance = \"lsp\", distance = 0),\n        Symbol(qualifiedName = \"pkg.Server\", kind = \"function\", score = 0.54, provenance = \"lsp\", distance = 1),\n    ),\n    edges = listOf(Edge(source = \"pkg.Server\", target = \"pkg.Auth\", edgeType = \"calls\"))\n)\nval output = encode(payload)\n```\n\nOutput:\n```\nGCF tool=context_for_task budget=5000 tokens=1847 symbols=2 edges=1\n## targets\n@0 fn pkg.Auth 0.78 lsp\n## related\n@1 fn pkg.Server 0.54 lsp\n## edges [1]\n@0\u003c@1 calls\n```\n\n## Decode\n\n```kotlin\nval p = decode(input)\nprintln(\"${p.tool} ${p.symbols.size} symbols ${p.edges.size} edges\")\n```\n\nThrows `DecodeException` on invalid input.\n\n## Session Deduplication\n\nTrack transmitted symbols across multiple tool responses. Previously-sent symbols become bare references instead of full declarations:\n\n```kotlin\nval session = Session()\n\nval out1 = encodeWithSession(payload1, session) // full declarations\nval out2 = encodeWithSession(payload2, session) // reused symbols as \"@N  # previously transmitted\"\n```\n\nBy the 5th call in a session: 92.7% token savings vs JSON.\n\n## Streaming Encode\n\nWrite GCF output incrementally as symbols and edges arrive. Zero buffering, O(1) memory per row:\n\n```kotlin\nval enc = StreamEncoder(writer, \"context_for_task\", StreamOptions(tokenBudget = 5000))\n\nenc.writeSymbol(Symbol(qualifiedName = \"pkg.Auth\", kind = \"function\", score = 0.95, provenance = \"lsp\", distance = 0))\nenc.writeEdge(Edge(source = \"pkg.Server\", target = \"pkg.Auth\", edgeType = \"calls\"))\nenc.close()  // emits ## _summary trailer\n```\n\nOutput uses `[?]` deferred counts and `## _summary` trailer. Standard `decode()` handles streaming output with no changes. Thread-safe via `@Synchronized`.\n\n## Delta Encoding\n\nWhen the consumer already has a prior context pack, send only what changed:\n\n```kotlin\nval delta = DeltaPayload(\n    tool = \"context_for_task\",\n    baseRoot = \"aaa111\",\n    newRoot = \"bbb222\",\n    removed = listOf(Symbol(qualifiedName = \"pkg.OldFunc\", kind = \"function\")),\n    added = listOf(Symbol(qualifiedName = \"pkg.NewFunc\", kind = \"function\", score = 0.85, provenance = \"rwr\")),\n    deltaTokens = 30,\n    fullTokens = 200\n)\n\nval output = encodeDelta(delta)\n```\n\n81.2% savings on re-queries where the pack changed slightly.\n\n## Generic Encoding\n\nEncode any value (not just graph payloads) into GCF tabular format:\n\n```kotlin\nval data = mapOf(\n    \"employees\" to listOf(\n        mapOf(\"id\" to 1, \"name\" to \"Alice\", \"department\" to \"Engineering\", \"salary\" to 95000),\n        mapOf(\"id\" to 2, \"name\" to \"Bob\", \"department\" to \"Sales\", \"salary\" to 72000),\n    )\n)\nval output = encodeGeneric(data)\n```\n\nOutput:\n```\n## employees [2]{department,id,name,salary}\nEngineering|1|Alice|95000\nSales|2|Bob|72000\n```\n\nWorks on maps, lists, and primitives. Arrays of uniform maps get tabular rows. Nested maps use `## key` section headers.\n\n## API\n\n| Function | Description |\n|----------|-------------|\n| `encode(payload: Payload): String` | Encode a graph payload to GCF text |\n| `encodeGeneric(data: Any?): String` | Encode any value to GCF tabular format |\n| `decode(input: String): Payload` | Parse GCF text back to a Payload |\n| `encodeWithSession(payload: Payload, session: Session?): String` | Encode with session deduplication |\n| `encodeDelta(delta: DeltaPayload): String` | Encode a delta (added/removed only) |\n| `Session()` | Create a new session tracker (thread-safe) |\n\n## Types\n\n| Type | Purpose |\n|------|---------|\n| `Payload` | Full GCF payload: tool, budget, symbols, edges, pack root |\n| `Symbol` | Graph node: qualified name, kind, score, provenance, distance |\n| `Edge` | Directed relationship: source, target, edge type |\n| `DeltaPayload` | Diff between two packs: added/removed symbols and edges |\n| `Session` | Thread-safe tracker for multi-call deduplication |\n| `Components` | Score breakdown: blast radius, confidence, recency, distance |\n| `DecodeException` | Thrown on invalid GCF input |\n| `kindAbbrev` / `kindExpand` | Bidirectional kind abbreviation maps |\n\n## Benchmarks\n\n2,400+ LLM evaluations across 10 models, 3 providers, and 51 independent test runs.\n\n| | GCF | TOON | JSON |\n|---|---|---|---|\n| **Comprehension** (23 runs, 10 models) | **91.2%** | 68.8% | 54.1% |\n| **Generation** (28 runs, 9 models) | **5/5** | 1.0/5 | 5.0/5 |\n| **Input tokens** (500 symbols) | **11,090** | 16,378 | 53,341 |\n| **Output tokens** (100 symbols) | **5,976** | 8,937 | 16,121 |\n\nGCF 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)\n\n## Implementations\n\n| Language | Package | Repository |\n|----------|---------|-----------|\n| Go | `go get github.com/blackwell-systems/gcf-go` | [gcf-go](https://github.com/blackwell-systems/gcf-go) |\n| TypeScript | `npm install @blackwell-systems/gcf` | [gcf-typescript](https://github.com/blackwell-systems/gcf-typescript) |\n| Python | `pip install gcf-python` | [gcf-python](https://github.com/blackwell-systems/gcf-python) |\n| Rust | `cargo add gcf` | [gcf-rust](https://github.com/blackwell-systems/gcf-rust) |\n| Swift | Swift Package Manager | [gcf-swift](https://github.com/blackwell-systems/gcf-swift) |\n| Kotlin | JitPack | [gcf-kotlin](https://github.com/blackwell-systems/gcf-kotlin) |\n| MCP Proxy | `pip install gcf-proxy` | [gcf-proxy](https://github.com/blackwell-systems/gcf-proxy) (bidirectional, session dedup, HTTP frontend) |\n| Claude Code Plugin | `/plugin install` | [gcf-claude-plugin](https://github.com/blackwell-systems/gcf-claude-plugin) (one-command install, session stats hook) |\n| Codex Plugin | `codex plugin add` | [gcf-codex-plugin](https://github.com/blackwell-systems/gcf-codex-plugin) (one-command install, session stats hook) |\n| VS Code | `ext install blackwell-systems.gcf-vscode` | [gcf-vscode](https://marketplace.visualstudio.com/items?itemName=blackwell-systems.gcf-vscode) (syntax highlighting) |\n| n8n | `npm install n8n-nodes-gcf` | [gcf-n8n-nodes](https://github.com/blackwell-systems/gcf-n8n-nodes) (workflow encode/decode) |\n| Tree-sitter | `npm install tree-sitter-gcf` | [tree-sitter-gcf](https://github.com/blackwell-systems/tree-sitter-gcf) |\n\n**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.\n\n**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.\n\n## License\n\nMIT - [Dayna Blackwell](https://github.com/blackwell-systems)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackwell-systems%2Fgcf-kotlin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackwell-systems%2Fgcf-kotlin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackwell-systems%2Fgcf-kotlin/lists"}