codegraph

Codebase Graph (graphify wrapper)

Wraps the external graphify CLI (https://github.com/safishamsi/graphify, MIT license, distributed as the PyPI package graphifyy) to build a knowledge graph of a codebase — files, functions, classes, and their calls/imports/uses/inherits relationships — at graphify's own fixed output location, graphify-out/, where other skills query it directly.

Status: piloting. Validated on a real ~40 KSLOC FastAPI codebase (a structural lead — webhook_dispatcher.py → RetryPolicy, the bridge between two otherwise-separate subsystems — that a textual grep could not find, since the bridging file never mentions the target term) before this migration. Now rolling out to a small set of engineering volunteers piloting it on substantially larger codebases (500 KSLOC+), where graph.json itself can run to tens of MB and the scoped-query pattern below stops being optional and starts being the only thing that scales. Report findings (works well / doesn't / surprises) as an issue in this repo so this can graduate out of pilot status or be reworked.

How to generate / refresh the graph

Step 0 — scope the index (first run only)

Before running graphify update on the whole repo, take a quick look at what's actually there:

# Top-level dirs by file count — surfaces generated/vendored/other-language subtrees
for d in */; do n=$(find "$d" -type f | wc -l); echo "$n $d"; done | sort -rn | head -10

Then ask: is there one directory that holds essentially all the source you care about, separate from generated code, vendored third-party libraries, or bindings for other languages?

• Yes — point graphify update at that directory instead of . (e.g. graphify update src/ --no-cluster). Smaller, cleaner graph; less cross-language noise in affected/explain results.
• No (everything's genuinely mixed) — run graphify update . --no-cluster on the repo root. Validated on a real ~300 KSLOC, 8-language, 2425-file monorepo (google/protobuf): completed in 5m28s, 73K nodes / 254K edges, with affected/explain queries returning in ~3s — an unscoped run on a messy repo is workable, just expect occasional cross-language results.
• No, but multiple genuinely independent roots (e.g. sibling repos or workspace directories with no shared parent worth scoping to) — index each root separately, then combine: