GCF Structured Data Format
A compact, schema-free, lossless wire format for structured model and agent communication.
- Source repo
- blackwell-systems/gcf
- Stars
- ★ 52
- Last updated
- today
- License
- Apache-2.0
- FA score
- 59/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- MCP server maintainers who want smaller structured tool responses while retaining decodable types and structure.
- Not a fit if
- Teams required to keep JSON on the wire without an encode/decode step
- Organizations requiring unambiguous license metadata before adoption
- Teams needing a mature, stable .NET SDK
- Source review
- 59/100 · Major gaps 2 safety controls not found
What does this agent do, and when should you use it?
GCF is a structured-data wire format for LLM and multi-turn agent interactions, not an autonomous task-running agent. Its generic profile encodes ordinary objects, arrays, and scalars, while its graph profile represents symbols, edges, and distance groups; data can be converted from and back to JSON, YAML, TOML, CSV, or MessagePack. The project supplies Go, TypeScript, Python, Rust, Swift, Kotlin, and .NET SDKs alongside CLIs, streaming encoders, an MCP proxy, Claude Code and Codex plugins, and editor integrations. For repeated interactions, local IDs, session deduplication, and delta encoding reduce retransmitted context, while streaming uses deferred counts and a summary trailer to emit rows incrementally. The repository reports more than 2,500 model evaluations, interoperability validation across 17 serialization formats, and over 43 billion lossless round-trips; these figures are project-reported.
An application passes deserialized objects, arrays, or scalars to the generic profile's encodeGeneric API—called encode_generic in the Python example. The encoder declares object-array fields once, emits pipe-separated positional rows, and can flatten fixed-shape nested objects into > path columns. For code intelligence and knowledge graphs, the graph profile's encode function accepts Payload, Symbol, and Edge values, replaces repeated identifiers in edges with local IDs such as @0, and produces sections such as targets, related, and edges. decode() restores the structured value and can convert it to JSON, YAML, TOML, CSV, or MessagePack. A streaming encoder can emit [?], process cursor or traversal rows incrementally, and finish with a ##! summary containing the final counts. Across turns, previously declared symbols may be sent as references and changed context as deltas; gcf-proxy adds bidirectional conversion, session deduplication, and an HTTP frontend around an existing MCP server without source changes.
- MCP server maintainers who want smaller structured tool responses while retaining decodable types and structure.
- Multi-agent workflow developers repeatedly handing the same structured context between models and seeking lower token use.
- Code-intelligence or knowledge-graph systems that need compact symbols, relationship edges, and distance groups.
- Services processing large database cursors or graph traversals that must emit rows without buffering the full result.
- Applications ingesting JSON, YAML, TOML, CSV, or MessagePack that want one model-facing representation.
- Claude Code or Codex teams wanting the documented plugins and session-statistics hooks.
How do you install or deploy this agent?
Install the SDK for the implementation language. The supplied material does not state minimum language versions or credential requirements.
pip install gcf-pythonnpm install @blackwell-systems/gcfgo get github.com/blackwell-systems/gcf-gocargo add gcfdotnet add package BlackwellSystems.GcfTo wrap an existing MCP server, install the proxy:
pip install gcf-proxyThe project also lists Swift Package Manager, Kotlin/JitPack, Claude Code and Codex plugins, and integrations for VS Code, JetBrains, Zed, n8n, and tree-sitter. The supplied material does not include complete copyable installation arguments for the plugins and several of those integrations.
How do you use this agent?
This first Python example encodes ordinary structured data with encode_generic and requires no API key:
from gcf import encode_generic
output = encode_generic({
"employees": [
{"id": 1, "name": "Alice", "department": "Engineering", "salary": 95000},
{"id": 2, "name": "Bob", "department": "Sales", "salary": 72000},
{"id": 3, "name": "Carol", "department": "Marketing", "salary": 85000},
],
})Use the graph profile for code relationships:
from gcf import encode, Payload, Symbol, Edge
output = encode(Payload(
tool="context_for_task", token_budget=5000, tokens_used=1847,
symbols=[
Symbol(qualified_name="github.com/org/repo/pkg.AuthMiddleware", kind="function", score=0.78, provenance="lsp_resolved", distance=0),
Symbol(qualified_name="github.com/org/repo/pkg.NewServer", kind="function", score=0.54, provenance="lsp_resolved", distance=1),
],
edges=[Edge(source="github.com/org/repo/pkg.NewServer", target="github.com/org/repo/pkg.AuthMiddleware", edge_type="calls")],
))Use the SDK's decode() operation to restore data or output JSON, YAML, TOML, CSV, or MessagePack. The source states that a CLI is included with the six original language SDKs, but it does not provide the precise CLI invocation syntax here.
What are this agent's strengths and limitations?
- One grammar covers general structured values and graph data with nodes, edges, and distance groups, with conversion paths for JSON, YAML, TOML, CSV, and MessagePack.
- The project reports 50–92% fewer tokens than JSON, plus further reductions from local IDs, session deduplication, and delta encoding.
- All seven language implementations commit to zero runtime dependencies beyond their standard libraries.
- Deferred counts and a summary trailer support constant-memory row streaming for large cursors and graph traversals.
- Documented integration paths include an MCP proxy, Claude Code and Codex plugins, and tooling for several editors and workflow environments.
- Adopters must add GCF encoding and decoding to their data path; systems that only understand established formats still require boundary conversion.
- The supplied license information conflicts: repository metadata and the badge say Apache-2.0, while the implementation section and license heading say MIT.
- The comprehension, token-efficiency, and TOON corruption figures are reported by the project; no independent replication is included in the supplied evidence.
- Component maturity varies: the listed .NET release is 0.1.0, while most other SDKs are 2.5.2 or later.
- Session deduplication and delta encoding require local IDs and persistent multi-turn state, adding lifecycle management beyond independent payload encoding.
How does this agent compare with similar options?
Compared with JSON, GCF removes repeated field names through shared headers, positional rows, and local IDs; the project reports 50–92% token savings, at the cost of an additional codec boundary. Unlike Protobuf, it requires no .proto schema and remains directly model-readable; unlike MessagePack, it is not binary. The project positions TOON as its main compact-text alternative and reports that GCF wins token efficiency on 15 of 16 datasets and reaches 91.2% comprehension on complex graphs versus 68.8% for TOON. These comparative figures come from the project's own evaluations.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| GCF Structured Data Format This agent | 59 · Major gaps | Library / SDKFree | ★ 52 | today | — | Codex · Claude Code |
| LeanCTX Context Intelligence | 75 · Good | CLIFree + model costs | ★ 3.8k | 1d ago | Rust | Codex · Claude Code · OpenAI API · Claude API |
| MCP Memory Service | 68 · Some gaps | MCP serverFree | ★ 2k | 1d ago | Python | ChatGPT · Codex · Claude Code · Claude.ai |
| Pydantic Deep Agents | 68 · Some gaps | CLIFree + model costs | ★ 1.1k | 1mo ago | Python | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence presents the core codec as a generally local and reversible transformation, and the differential-fuzz workflow explicitly grants read-only contents permission. The README explains encoding, references, and decoding, and attributes the author and research. Deductions apply because there is no user-confirmation mechanism or guidance for sensitive-data handling and log redaction; least-privilege settings are not explicit for every workflow, and proxy or conversion data boundaries are incomplete. Dependency security rests largely on an asserted zero-runtime-dependency policy, while this repository's package.json contains several range-pinned tooling dependencies without a supplied lockfile, audit process, commit pinning, or vulnerability response. Unknown publisher identity is not treated as suspicious.
The repository supplies a coverage gate, nightly cross-SDK differential fuzzing, and an NxN interoperability script. The scripts report unavailable tools, timeouts, mismatches, and failing exit states intelligibly. Installation spans several ecosystems and CI declares its toolchains, but verification depends on multiple external repositories and a fixed local directory layout. Self-consistency is materially reduced by the README saying MIT while LICENSE is Apache-2.0, the matrix script describing GCF v2.0 while the README advertises spec v3.5.1, and potentially confusing zero-dependency wording alongside repository tooling dependencies.
The README thoroughly identifies audiences and scenarios including MCP, agent handoffs, structured generation, code graphs, multi-format conversion, streaming, and multi-turn sessions. It also distinguishes generic and graph profiles with concrete examples. Deductions apply because there is no executable trigger or selection policy, input-size threshold, or fallback rule. Environment coverage is broad, but the matrix script assumes HOME/code paths, numerous toolchains, and separately checked-out SDK repositories, so setup is not portable without adaptation.
Information architecture, examples, format explanations, installation commands, and documentation navigation are strong; an FAQ is linked, and specification and SDK versions are named. The license criterion is sharply reduced because the root LICENSE and supplied metadata say Apache-2.0 while the README says MIT. No changelog, migration path, or clear compatibility policy is included in the supplied material. Known limitations are thin: the text emphasizes advantages without systematically documenting unsuitable cases, resource limits, security boundaries, or failure modes. Maintenance can be associated with blackwell-systems and Dayna Blackwell, but governance, support, release ownership, and security-reporting procedures are not stated.
The examples are compact and readable and demonstrate restoration to structured values, streaming, local identifiers, session deduplication, and multiple implementations, adequately supporting output usability from static evidence. The structural approach plausibly adds value over repeated JSON. However, savings of 50–92%, 99%, 94.4%, and over 43 billion failure-free round trips are principally README claims; the supplied files do not contain raw results, statistical methodology, or a full cost model, so marginal value and cost-benefit do not receive full marks.
Many major claims are connected to a specification, benchmark pages, papers, coverage workflows, or test scripts. The workflow and matrix code also provide some cross-file corroboration that conformance and interoperability testing are intended. Deductions apply because the supplied evidence omits the specification, fixtures, complete benchmark data, CI results, and paper contents, preventing static confirmation of the advertised counts and rates. The README also blends measured observations, causal research interpretations, marketing comparisons, and permanent commitments without consistently separating fact from inference.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Resolve the licensing conflict before adoption or redistribution: the README says MIT, while the root LICENSE and supplied metadata say Apache-2.0.
- Do not treat the 43B failure-free round trips, 100% comprehension, or stated savings as independently verified; this assessment executed nothing and was not supplied raw results or CI records.
- Before processing confidential or personal data, separately review proxy, logging, telemetry, caching, session-deduplication, and cross-format data flows; the supplied material has no sensitive-data policy.
- Cross-language testing depends on several external repositories, toolchains, and fixed directory conventions. Pin exact revisions and verify every SDK against specification v3.5.1 before relying on interoperability.
- package.json uses version ranges and no lockfile or dependency-audit evidence was supplied; lock and review dependencies in supply-chain-sensitive deployments.
FAQ
Does GCF require a model API or paid service?
Can it replace JSON everywhere?
Is MCP mandatory?
gcf-proxy is an optional integration for wrapping existing MCP servers.How does streaming work when the row count is unknown?
[?] in the header, streams rows as they arrive, and closes with a ##! summary containing the actual counts.