{"id":51508554,"url":"https://github.com/blackwell-systems/gcf-swift","last_synced_at":"2026-07-08T03:30:40.273Z","repository":{"id":362749112,"uuid":"1260618800","full_name":"blackwell-systems/gcf-swift","owner":"blackwell-systems","description":"GCF Swift 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-23T20:16:59.000Z","size":1586,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T21:13:59.435Z","etag":null,"topics":["ai-agents","apple","data-serialization","decoder","encoder","gcf","graph-compact-format","ios","json-alternative","llm","macos","mcp","mcp-tools","model-context-protocol","structured-data","swift","swift-package-manager","token-efficiency","token-optimization","wire-format"],"latest_commit_sha":null,"homepage":"https://www.gcformat.com","language":"Swift","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:29:48.000Z","updated_at":"2026-06-23T20:17:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/blackwell-systems/gcf-swift","commit_stats":null,"previous_names":["blackwell-systems/gcf-swift"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/blackwell-systems/gcf-swift","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcf-swift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcf-swift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcf-swift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcf-swift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blackwell-systems","download_url":"https://codeload.github.com/blackwell-systems/gcf-swift/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcf-swift/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","apple","data-serialization","decoder","encoder","gcf","graph-compact-format","ios","json-alternative","llm","macos","mcp","mcp-tools","model-context-protocol","structured-data","swift","swift-package-manager","token-efficiency","token-optimization","wire-format"],"created_at":"2026-07-08T03:30:39.649Z","updated_at":"2026-07-08T03:30:40.265Z","avatar_url":"https://github.com/blackwell-systems.png","language":"Swift","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-swift/actions\"\u003e\u003cimg src=\"https://github.com/blackwell-systems/gcf-swift/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-swift\n\nSwift 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 to your `Package.swift`:\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/blackwell-systems/gcf-swift.git\", from: \"0.3.0\"),\n]\n```\n\nThen add `\"GCF\"` to your target's dependencies:\n\n```swift\n.target(name: \"MyApp\", dependencies: [\"GCF\"]),\n```\n\nZero dependencies. Single module. Supports macOS 12+ and iOS 15+. Don'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```swift\nimport GCF\n\nlet output = encodeGeneric([\n    \"employees\": [\n        [\"id\": 1, \"name\": \"Alice\", \"department\": \"Engineering\", \"salary\": 95000],\n        [\"id\": 2, \"name\": \"Bob\", \"department\": \"Sales\", \"salary\": 72000],\n    ] as [[String: Any]]\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```swift\nlet p = Payload(\n    tool: \"context_for_task\", tokensUsed: 1847, tokenBudget: 5000,\n    symbols: [\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: [Edge(source: \"pkg.Server\", target: \"pkg.Auth\", edgeType: \"calls\")]\n)\nlet output = 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```swift\nlet p = try decode(input)\nprint(p.tool, p.symbols.count, \"symbols\", p.edges.count, \"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```swift\nlet session = Session()\n\nlet out1 = encodeWithSession(payload1, session: session) // full declarations\nlet out2 = encodeWithSession(payload2, session: 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```swift\nlet enc = StreamEncoder(writer: myWriter, tool: \"context_for_task\", options: 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 NSLock.\n\n## Delta Encoding\n\nWhen the consumer already has a prior context pack, send only what changed:\n\n```swift\nlet delta = DeltaPayload(\n    tool: \"context_for_task\",\n    baseRoot: \"aaa111\",\n    newRoot: \"bbb222\",\n    removed: [Symbol(qualifiedName: \"pkg.OldFunc\", kind: \"function\")],\n    added: [Symbol(qualifiedName: \"pkg.NewFunc\", kind: \"function\", score: 0.85, provenance: \"rwr\")],\n    deltaTokens: 30,\n    fullTokens: 200\n)\n\nlet output = encodeDelta(delta)\n```\n\n81.2% savings on re-queries where the pack changed slightly.\n\n## Generic Encoding\n\nEncode any Swift value (not just graph payloads) into GCF tabular format:\n\n```swift\nlet data: [String: Any] = [\n    \"employees\": [\n        [\"id\": 1, \"name\": \"Alice\", \"department\": \"Engineering\", \"salary\": 95000],\n        [\"id\": 2, \"name\": \"Bob\", \"department\": \"Sales\", \"salary\": 72000],\n    ] as [[String: Any]]\n]\nlet 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 dictionaries, arrays, 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(_ payload: Payload) -\u003e String` | Encode a graph payload to GCF text |\n| `encodeGeneric(_ data: Any?) -\u003e String` | Encode any value to GCF tabular format |\n| `decode(_ input: String) throws -\u003e Payload` | Parse GCF text back to a Payload |\n| `encodeWithSession(_ payload: Payload, session: Session?) -\u003e String` | Encode with session deduplication |\n| `encodeDelta(_ delta: DeltaPayload) -\u003e 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| `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-swift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackwell-systems%2Fgcf-swift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackwell-systems%2Fgcf-swift/lists"}