Which graph format should I use?

[amacsmith]

Q: I want to register my repo. Which graph format should I use?

A: Pick by what your tool already produces. If you have a choice, use the decision tree below.

Decision tree

• You want AST/structural detail — files, classes, functions, calls → use understand-anything@1. Best fit for general-purpose code understanding agents that need to navigate by symbol.
• You want a dependency graph with module/community detection → use gitnexus@1. First-class support for Louvain communities and import-edge weights; agents that ask "what's in the same neighborhood as X" love this shape.
• You want a code-review or symbol-level shape → use code-review-graph@1. Optimized for diff-aware traversal — files, classes, tests, and the references between them.
• You have a flat text dump (Repomix, gitingest, codebase-digest) → use bundle@1. The format wraps any of the popular packer outputs with a small metadata envelope so it can sit next to real graphs in the registry without lying about its shape.
• None of the above; you have your own {nodes, edges} graph → use generic@1. The escape hatch. Lower discoverability (agents may not have format-specific UI) but always valid.

Tiers

understand-anything@1, gitnexus@1, code-review-graph@1, and bundle@1 are first-class — agents and the Pages viewer have format-aware rendering. generic@1 is fallback only. Adding a new first-class format is a PR: schemas/<name>@<int>.json plus an ok and bad fixture.

Specifications

The full protocol is at docs/spec/code-graph-protocol.md. Schemas live in schemas/. Each schema has fixtures showing a valid and an invalid example.

If your tool emits something none of the above models cleanly, open an Ideas thread or a PR with a schema and a real graph using it.