Code Graphs for flw Research

The caveat, measured

I asked your host's LSP for every reference to run_one in core/scripts/gates.py.

Zero of eight real callers. The cause: cli/flw.py reaches gates through sys.path.insert then import gates. Pyright can't resolve that, so the edge doesn't exist in the graph.

A second one in the same session: workspaceSymbol("collect") returned four hits, all from plugins/flow/ — a different project. The workspace root was a parent directory.

What this means. Dynamic imports, plugin registries, DI containers, string-keyed dispatch, anything resolved at runtime — those edges are missing and nothing tells you. Big enterprise Python is full of them. A graph that returns zero looks the same as a symbol nobody calls.

It doesn't kill the idea. It sets the rule: a graph is a fast first pass, not an authority. Any "nobody uses this" conclusion needs a grep to confirm.

Two layers, not one

The mistake would be building one thing. A whole-repo symbol graph is hundreds of thousands of tokens — you never want it in context. The high-level skeleton is a page and you always want it.

They depend on each other. findReferences needs a symbol name, so you can't ask "who calls X" until you know X exists. Layer 1 tells you. Layer 2 answers.

The landscape

CodeQL is out for many teams. The licence blocks private commercial repos without a per-committer seat.

Build once, query many — the CLI model

An index on disk queried by a CLI is a better fit for flw than an MCP server. MCP is a running process with per-host config. flw is host-agnostic and its whole model is a file plus a command. An index file is that shape.

Three of the four things you'd expect from it hold up. One doesn't.

The build-then-query options

On CodeGraph. Verified through the GitHub API rather than the page: 67,590 stars, 4,288 forks, created 2026-01-18, last push 2026-08-20, MIT. Real growth — but a seven-month-old project with 439 open issues and 157 watchers. A 430:1 star-to-watcher ratio is a hype signature, not a stability one. Its token-saving claims are self-reported. npm-distributed, which may matter in a locked-down environment.

GNU GLOBAL is the unhyped one that does exactly what you described. gtags builds, global -r symbol queries references. Thirty years of doing one thing.

The infra tier — what Meta actually had

You're remembering Glean. Meta open-sourced it in 2021 and it's still maintained. It's the real thing: typed, schema-defined facts about source code in a queryable database, with Angle, a Datalog-style query language.

An Angle query looks like this:

It answers questions like "all classes inheriting from exception that have a what method overriding a base" in milliseconds. Facts live in RocksDB. Incremental indexing is O(files changed), not O(repository).

The numbers are genuinely good

Simon Marlow — a Glean author — indexed all of Hackage outside Meta and published the comparison against hiedb:

Why it felt like infra is that it is infra. Glean works at Meta because Meta's build system emits index data as a by-product of compilation, across a monorepo, for thousands of engineers. Outside that, you hand-roll the pipeline that fed it.

Google's equivalent, Kythe, is the same story with a worse ending.

The part worth stealing

Glean ingests SCIP and LSIF. That's the tell. The valuable half of "AST infra" is the indexer — the thing that turns code into accurate facts. The Datalog engine is what makes it feel like infra, and it earns its keep at billions of facts and thousands of concurrent users.

At one-repo scale, with an agent asking a handful of questions, SQL over SQLite answers the same questions. Same facts, from the same indexers, minus the Haskell.

What I'd pick

Layer 2 — the graph

GNU GLOBAL first, because it's boring, installs anywhere, and is exactly build-then-query. CodeGraph if you want the agent-shaped one and can accept a seven-month-old dependency.

Serena stays the answer if you decide MCP is acceptable after all — MIT, 24.8k stars, 40+ languages, real language servers. But it's MCP-only, and that's a genuine mismatch with how flw is built.

Layer 1 — the skeleton

Parse with tree-sitter, extract definitions and references, rank by how often a symbol is referenced elsewhere, print the top N within a token budget. A function called by 20 others outranks a private helper called once. This is aider's approach and it's the part worth writing to disk.

What flw itself ships

None of it. flw stays stdlib-only, zero dependencies, language-agnostic. Bundling tree-sitter or an LSP client breaks all three, and it would put flw in the business of maintaining an indexer.

The dependency belongs in your repo and your environment, not in flw. Which also means your environment decides what's possible, not us.

So research does three things:

1. Probe what's available — Serena, host LSP, ctags, an existing index.
2. Verify it. Pick one known call edge, ask the graph, confirm with grep. Record whether it agreed.
3. Record the working recipe and its blind spots in .flw/extensions/flw-spec.md.

Step 2 is the one I'd have skipped a week ago. Today's test is why it's in the list.

What I could not confirm

• Whether Serena precomputes an index or queries on demand, and its startup cost on a large repo. The docs don't say. Worth a 20-minute trial on a real repo before committing.
• Whether scip-python is still maintained. SCIP moved from Sourcegraph to independent governance with a steering committee, but the CLI's last release was June 2024.
• Any independent measurement of the token saving. Aider's 1k default is a design choice, not a benchmark.

Sources

• oraios/serena — MCP toolkit, MIT
• Serena documentation
• microsoft/multilspy — LSP client library
• Building a better repository map with tree-sitter — aider
• aider repo map docs — the 1k token default
• Aider repository mapping system
• SCIP Code Intelligence Protocol and scip-code/scip
• The future of SCIP — governance move
• ast-grep/ast-grep
• joernio/joern — code property graphs
• CodeQL licensing comparison
• Glean and its build requirements
• Indexing code at scale with Glean — Engineering at Meta
• Indexing Hackage: Glean vs. hiedb — Simon Marlow, the outside-Meta account
• Kythe
• colbymchenry/codegraph
• GNU GLOBAL manual
• scip CLI reference — including expt-convert