https://github.com/blackwell-systems/gcf-go
GCF Go 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-go
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
Last synced: about 21 hours ago
JSON representation
GCF Go 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-go
- Owner: blackwell-systems
- License: mit
- Created: 2026-06-03T21:02:09.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-23T04:22:18.000Z (16 days ago)
- Last Synced: 2026-06-23T06:12:17.558Z (16 days ago)
- 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
- Language: Go
- Homepage: https://www.gcformat.com
- Size: 4.2 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# gcf-go
Go 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
```
go get github.com/blackwell-systems/gcf-go
```
Zero dependencies. Single package. Don't want to change code? Use the [MCP proxy](https://github.com/blackwell-systems/gcf-proxy) for zero-code adoption.
## CLI
Standalone 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.
```bash
# Install
go install github.com/blackwell-systems/gcf-go/cmd/gcf@latest
# Or download a binary from the latest release
# Usage
gcf encode < payload.json # JSON to GCF
gcf decode < payload.gcf # GCF to JSON
gcf stats < payload.json # token comparison
```
## Quick Start
```go
import gcf "github.com/blackwell-systems/gcf-go"
data := map[string]any{
"employees": []map[string]any{
{"id": 1, "name": "Alice", "department": "Engineering", "salary": 95000},
{"id": 2, "name": "Bob", "department": "Sales", "salary": 72000},
},
}
output := gcf.EncodeGeneric(data)
```
Output:
```
## employees [2]{department,id,name,salary}
Engineering|1|Alice|95000
Sales|2|Bob|72000
```
Works on any Go value: maps, slices, structs. One header declares field names, rows are positional values.
## Graph Profile
For code graph data with symbols, edges, and distance groups:
```go
p := &gcf.Payload{
Tool: "context_for_task", TokenBudget: 5000, TokensUsed: 1847,
Symbols: []gcf.Symbol{
{QualifiedName: "pkg.Auth", Kind: "function", Score: 0.78, Provenance: "lsp", Distance: 0},
{QualifiedName: "pkg.Server", Kind: "function", Score: 0.54, Provenance: "lsp", Distance: 1},
},
Edges: []gcf.Edge{{Source: "pkg.Server", Target: "pkg.Auth", EdgeType: "calls"}},
}
output := gcf.Encode(p)
```
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
```go
p, err := gcf.Decode(input)
if err != nil {
log.Fatal(err)
}
fmt.Println(p.Tool, len(p.Symbols), "symbols", len(p.Edges), "edges")
```
## Session Deduplication
Track transmitted symbols across multiple tool responses. Previously-sent symbols become bare references instead of full declarations:
```go
sess := gcf.NewSession()
out1 := gcf.EncodeWithSession(payload1, sess) // full declarations
out2 := gcf.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:
```go
enc := gcf.NewStreamEncoder(w, "context_for_task", gcf.StreamOptions{TokenBudget: 5000})
// Symbols emit immediately as they're discovered.
enc.WriteSymbol(gcf.Symbol{QualifiedName: "pkg.Auth", Kind: "function", Score: 0.95, Provenance: "lsp", Distance: 0})
enc.WriteSymbol(gcf.Symbol{QualifiedName: "pkg.Server", Kind: "function", Score: 0.60, Provenance: "lsp", Distance: 1})
// Edges emit immediately too.
enc.WriteEdge(gcf.Edge{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 sections=targets:1,related:1,edges:1
```
The `[?]` 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.
## Delta Encoding
When the consumer already has a prior context pack, send only what changed:
```go
delta := &gcf.DeltaPayload{
Tool: "context_for_task",
BaseRoot: "aaa111",
NewRoot: "bbb222",
Removed: []gcf.Symbol{{QualifiedName: "pkg.OldFunc", Kind: "function"}},
Added: []gcf.Symbol{{QualifiedName: "pkg.NewFunc", Kind: "function", Score: 0.85, Provenance: "rwr"}},
DeltaTokens: 30,
FullTokens: 200,
}
output := gcf.EncodeDelta(delta)
```
81.2% savings on re-queries where the pack changed slightly.
## Generic Encoding
Encode any Go value (not just graph payloads) into GCF tabular format:
```go
data := map[string]any{
"employees": []map[string]any{
{"id": 1, "name": "Alice", "department": "Engineering", "salary": 95000},
{"id": 2, "name": "Bob", "department": "Sales", "salary": 72000},
},
}
output := gcf.EncodeGeneric(data)
```
Output:
```
## employees [2]{id,name,department,salary}
1|Alice|Engineering|95000
2|Bob|Sales|72000
```
Works on maps, slices, structs, and primitives. Arrays of uniform objects get tabular rows. Nested objects use `## key` section headers.
## API
| Function | Description |
|----------|-------------|
| `Encode(p *Payload) string` | Encode a graph payload to GCF text |
| `EncodeGeneric(data any) string` | Encode any value to GCF tabular format |
| `Decode(input string) (*Payload, error)` | Parse GCF text back to a Payload |
| `EncodeWithSession(p *Payload, s *Session) string` | Encode with session deduplication |
| `EncodeDelta(d *DeltaPayload) string` | Encode a delta (added/removed only) |
| `NewStreamEncoder(w, tool, opts) *StreamEncoder` | Create a streaming encoder (zero-buffering) |
| `NewSession() *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 |
| `StreamEncoder` | Streaming encoder: WriteSymbol, WriteEdge, WriteBareRef, Close |
| `StreamOptions` | Config for streaming: TokenBudget, TokensUsed, PackRoot, Session |
| `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)