{"id":51508559,"url":"https://github.com/blackwell-systems/gcf-go","last_synced_at":"2026-07-08T03:30:41.948Z","repository":{"id":362370140,"uuid":"1258710958","full_name":"blackwell-systems/gcf-go","owner":"blackwell-systems","description":"GCF Go 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-23T04:22:18.000Z","size":4400,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T06:12:17.558Z","etag":null,"topics":["ai-agents","anthropic","data-serialization","decoder","encoder","gcf","gemini","go","golang","graph-compact-format","json-alternative","llm","mcp","mcp-tools","model-context-protocol","openai","structured-data","token-efficiency","token-optimization","wire-format"],"latest_commit_sha":null,"homepage":"https://www.gcformat.com","language":"Go","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":"ROADMAP.md","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-03T21:02:09.000Z","updated_at":"2026-06-23T04:16:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/blackwell-systems/gcf-go","commit_stats":null,"previous_names":["blackwell-systems/gcf-go"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/blackwell-systems/gcf-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcf-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcf-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcf-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcf-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blackwell-systems","download_url":"https://codeload.github.com/blackwell-systems/gcf-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcf-go/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","anthropic","data-serialization","decoder","encoder","gcf","gemini","go","golang","graph-compact-format","json-alternative","llm","mcp","mcp-tools","model-context-protocol","openai","structured-data","token-efficiency","token-optimization","wire-format"],"created_at":"2026-07-08T03:30:41.487Z","updated_at":"2026-07-08T03:30:41.942Z","avatar_url":"https://github.com/blackwell-systems.png","language":"Go","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-go/actions\"\u003e\u003cimg src=\"https://github.com/blackwell-systems/gcf-go/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-go\n\nGo 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\n```\ngo get github.com/blackwell-systems/gcf-go\n```\n\nZero dependencies. Single package. Don't want to change code? Use the [MCP proxy](https://github.com/blackwell-systems/gcf-proxy) for zero-code adoption.\n\n## CLI\n\nStandalone binaries are attached to each [release](https://github.com/blackwell-systems/gcf-go/releases). The CLI is optional; it's for converting files from the command line without writing code.\n\n```bash\n# Install\ngo install github.com/blackwell-systems/gcf-go/cmd/gcf@latest\n\n# Or download a binary from the latest release\n\n# Usage\ngcf encode \u003c payload.json    # JSON to GCF\ngcf decode \u003c payload.gcf     # GCF to JSON\ngcf stats  \u003c payload.json    # token comparison\n```\n\n## Quick Start\n\n```go\nimport gcf \"github.com/blackwell-systems/gcf-go\"\n\ndata := map[string]any{\n    \"employees\": []map[string]any{\n        {\"id\": 1, \"name\": \"Alice\", \"department\": \"Engineering\", \"salary\": 95000},\n        {\"id\": 2, \"name\": \"Bob\", \"department\": \"Sales\", \"salary\": 72000},\n    },\n}\noutput := gcf.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 any Go value: maps, slices, structs. One header declares field names, rows are positional values.\n\n## Graph Profile\n\nFor code graph data with symbols, edges, and distance groups:\n\n```go\np := \u0026gcf.Payload{\n    Tool: \"context_for_task\", TokenBudget: 5000, TokensUsed: 1847,\n    Symbols: []gcf.Symbol{\n        {QualifiedName: \"pkg.Auth\", Kind: \"function\", Score: 0.78, Provenance: \"lsp\", Distance: 0},\n        {QualifiedName: \"pkg.Server\", Kind: \"function\", Score: 0.54, Provenance: \"lsp\", Distance: 1},\n    },\n    Edges: []gcf.Edge{{Source: \"pkg.Server\", Target: \"pkg.Auth\", EdgeType: \"calls\"}},\n}\noutput := gcf.Encode(p)\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```go\np, err := gcf.Decode(input)\nif err != nil {\n    log.Fatal(err)\n}\nfmt.Println(p.Tool, len(p.Symbols), \"symbols\", len(p.Edges), \"edges\")\n```\n\n## Session Deduplication\n\nTrack transmitted symbols across multiple tool responses. Previously-sent symbols become bare references instead of full declarations:\n\n```go\nsess := gcf.NewSession()\n\nout1 := gcf.EncodeWithSession(payload1, sess) // full declarations\nout2 := gcf.EncodeWithSession(payload2, sess) // 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. Ideal for MCP servers that walk large graphs or paginate results:\n\n```go\nenc := gcf.NewStreamEncoder(w, \"context_for_task\", gcf.StreamOptions{TokenBudget: 5000})\n\n// Symbols emit immediately as they're discovered.\nenc.WriteSymbol(gcf.Symbol{QualifiedName: \"pkg.Auth\", Kind: \"function\", Score: 0.95, Provenance: \"lsp\", Distance: 0})\nenc.WriteSymbol(gcf.Symbol{QualifiedName: \"pkg.Server\", Kind: \"function\", Score: 0.60, Provenance: \"lsp\", Distance: 1})\n\n// Edges emit immediately too.\nenc.WriteEdge(gcf.Edge{Source: \"pkg.Server\", Target: \"pkg.Auth\", EdgeType: \"calls\"})\n\n// Close emits the ## _summary trailer with final counts.\nenc.Close()\n```\n\nOutput:\n```\nGCF tool=context_for_task budget=5000\n## targets\n@0 fn pkg.Auth 0.95 lsp\n## related\n@1 fn pkg.Server 0.60 lsp\n## edges [?]\n@0\u003c@1 calls\n## _summary symbols=2 edges=1 sections=targets:1,related:1,edges:1\n```\n\nThe `[?]` marker signals deferred count. The `## _summary` trailer provides counts after the data. The LLM has both the data and the counts in context. Standard `Decode()` handles streaming output with no changes.\n\n## Delta Encoding\n\nWhen the consumer already has a prior context pack, send only what changed:\n\n```go\ndelta := \u0026gcf.DeltaPayload{\n    Tool:     \"context_for_task\",\n    BaseRoot: \"aaa111\",\n    NewRoot:  \"bbb222\",\n    Removed:  []gcf.Symbol{{QualifiedName: \"pkg.OldFunc\", Kind: \"function\"}},\n    Added:    []gcf.Symbol{{QualifiedName: \"pkg.NewFunc\", Kind: \"function\", Score: 0.85, Provenance: \"rwr\"}},\n    DeltaTokens: 30,\n    FullTokens:  200,\n}\n\noutput := gcf.EncodeDelta(delta)\n```\n\n81.2% savings on re-queries where the pack changed slightly.\n\n## Generic Encoding\n\nEncode any Go value (not just graph payloads) into GCF tabular format:\n\n```go\ndata := map[string]any{\n    \"employees\": []map[string]any{\n        {\"id\": 1, \"name\": \"Alice\", \"department\": \"Engineering\", \"salary\": 95000},\n        {\"id\": 2, \"name\": \"Bob\", \"department\": \"Sales\", \"salary\": 72000},\n    },\n}\noutput := gcf.EncodeGeneric(data)\n```\n\nOutput:\n```\n## employees [2]{id,name,department,salary}\n1|Alice|Engineering|95000\n2|Bob|Sales|72000\n```\n\nWorks on maps, slices, structs, and primitives. Arrays of uniform objects get tabular rows. Nested objects use `## key` section headers.\n\n## API\n\n| Function | Description |\n|----------|-------------|\n| `Encode(p *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, error)` | Parse GCF text back to a Payload |\n| `EncodeWithSession(p *Payload, s *Session) string` | Encode with session deduplication |\n| `EncodeDelta(d *DeltaPayload) string` | Encode a delta (added/removed only) |\n| `NewStreamEncoder(w, tool, opts) *StreamEncoder` | Create a streaming encoder (zero-buffering) |\n| `NewSession() *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| `StreamEncoder` | Streaming encoder: WriteSymbol, WriteEdge, WriteBareRef, Close |\n| `StreamOptions` | Config for streaming: TokenBudget, TokensUsed, PackRoot, Session |\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-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackwell-systems%2Fgcf-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackwell-systems%2Fgcf-go/lists"}