M05 · The Tool Landscape: CodeGraph, okf-rs, and Friends

Learning objectives Intermediate

Graphify (M04) is one point in a design space that filled up fast. This module maps the rest of it — not as a product roundup, but as a set of design decisions: where the graph lives, how it stays fresh, what it labels, and where your code goes. Learn the axes and every future tool launch becomes a 10-minute evaluation instead of a leap of faith.

CodeGraph: the database bet

Where Graphify's canonical output is three files an assistant reads, CodeGraph's center of gravity is the query path: when an AI agent asks "what calls this function?" or "trace the full impact of changing this module," CodeGraph responds in a single MCP tool call — entry points, related symbols, and relevant code snippets. No file-by-file exploration, no agent loops, no context windows bloated with irrelevant file contents. Recall from M00 that most agent tokens are exploration, not reasoning; CodeGraph's design attacks exactly that line item.

The installer is deliberately zero-configuration: it auto-detects which AI tools are present — Claude Code, Cursor, Codex CLI, OpenCode, Gemini CLI, and others — and wires up the MCP integration without manual setup:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# Windows PowerShell
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

# then, per project:
cd your-project
codegraph init -i     # -i = initial full-graph build

Practical notes worth keeping: the initial build on very large projects (100,000+ files) can take ten minutes or more — a one-time cost, after which all sync is incremental. macOS users should install Xcode command-line tools first (xcode-select --install); the fallback compatibility mode runs 5–10× slower. Default exclusions cover node_modules, vendor, dist, build, target, .venv, gitignored files, and files over 1 MB. Supported languages: TypeScript, Python, Rust, Java, Go, Swift, Kotlin, C/C++, C#, Ruby, PHP, Dart, plus template languages like Svelte and Vue — with the deepest coverage in TypeScript, Python, Rust, and Go, and Objective-C listed as partial.

CodeGraph's benchmarks: the best table in the field

CodeGraph's team ran the most rigorous comparison published so far: seven real open-source projects in seven languages, identical exploration tasks, the same model (Claude Opus 4.7 in headless mode, claude -p), four runs per arm, medians reported — the sole variable being whether the graph was available. Vendor-reported, but methodologically serious. Here is the table, and then the three patterns that matter more than the table:

Aggregates: 57% fewer tokens, 71% fewer tool calls, 46% faster responses, 35% lower costs. Now the patterns:

Pattern 1 — size correlates with savings. On VS Code's 10,000-file monorepo, token usage dropped from 2.8 million to 601,000 per benchmark run. On Excalidraw, from 3.5 million to 344,000. The larger the haystack, the more the AI flails without a map — the same corpus-topology law behind Graphify's 6.8×–49× spread in M04, seen from the other side.

Pattern 2 — Rust benefits disproportionately. Tokio's cost fell 82% ($2.41 → $0.42). The likely cause: Rust's module system — mod declarations, use paths, pub use re-exports, nested hierarchies — creates exploration paths that punish agent-based traversal hardest, and the graph resolves them in one query.

Pattern 3 — small repos see diminishing returns. OkHttp managed 13%; Gin 34%. At small scale brute force isn't that punishing, so the map's marginal value shrinks — the ~500-file floor again, now with per-language data.

And the caveat that reframes everything: these are not model improvements. Same model in both arms. Every saved token was mechanical file exploration eliminated — work that contributed nothing to answer quality. As the CodeGraph write-up put it: the fastest way to make an AI coding tool better might not be to make it smarter — it might be to give it a map.

The auto-sync architecture: three layers of staying fresh

Layer 1 — native OS file watchers. macOS FSEvents, Windows ReadDirectoryChangesW, Linux inotify — the lowest-level change-notification mechanism each OS provides. No polling, no CPU overhead; when a file is saved, the OS pushes the notification.

Layer 2 — debounced batching. A two-second quiet window collects all changes and collapses them into a single incremental sync. A refactor that touches five files in rapid succession triggers one re-index, not five. (Incremental parsing from M03 is what makes each sync proportional to the edit.)

Layer 3 — staleness flags and reconnection reconciliation. Files not yet synchronized are explicitly marked stale, so agents know to read them directly rather than trust outdated graph data. When an AI tool reconnects, a fast (size, mtime) comparison with content-hash verification identifies only the changed files to resync.

The result: an index that stays current with zero developer attention — "there is no rebuild-the-index step in anyone's workflow." Layer 3 deserves special respect: it is the only layer that handles its own failure, telling the consumer "don't trust me on these files yet." Hold that thought — M11 is an entire module about graph-freshness systems that lack such a layer, and the silent, documented ways they rot.

Framework route recognition

One CodeGraph feature earns its own section because it solves a debugging chore every API developer knows: "which handler processes POST /api/users?" Answering that by hand means finding the route config, tracing to the view, verifying the middleware — multiple search-and-verify cycles through indirection that exists precisely to keep routing declarative.

CodeGraph natively recognizes routing patterns across 14 web frameworks, covering all four routing paradigms:

With that in the graph, the URL maps directly to the handler function — through middleware chains, route includes, and decorator stacks — in a single query. For teams managing microservices or large API surfaces, this feature alone can justify the installation.

okf-rs: the Markdown-bundle bet

The output difference is philosophical. Where CodeGraph's graph lives in codegraph.db (query it through the tool), okf-rs generates a knowledge/ directory — one .md file per module, struct, enum, function, or method:

$ okf-rs generate .
Generated 146 concepts into knowledge
  Module 16   Struct 18   Enum 6   Function 87   Method 19

$ okf-rs validate
knowledge — no issues found

A single generated concept looks like this — remember the shape; you'll be writing these by hand in M06:

---
type: Rust Method
title: verify_token
resource: src/main.rs#L4-L6
generated:
  by: okf-rs/0.1.0
---

## Signature
`fn verify_token(&self, token: &str) -> bool`

## Calls
- [decode_jwt](../../../functions/src/Auth/decode_jwt.md)

Its design principles read like a checklist of everything this track has taught: Open — the output is the artifact, no runtime needed to read it. Fast — native Rust core on tree-sitter, not a compiler frontend. Deterministic — identical source produces byte-identical output (no timestamps, no unordered-map noise; M03's reproducibility argument as a hard guarantee). AI-ready without requiring AI — structured enough for an LLM to consume, no LLM involved in producing it.

And the feature list runs deep for a young tool. Highlights, grouped:

• Extraction: 11 languages (Rust, Python, TypeScript, JavaScript, Go, Java, C#, PHP, Kotlin, C/C++, Swift) with per-language visibility rules (M03's table); a resolved call graph covering bare, method/self/this, static, scoped, and qualified calls; optional LSP-backed disambiguation (--lsp, via rust-analyzer/pyright); content-hash incremental caching and a watch mode with debouncing.
• Search: exact/substring, ranked full-text (Tantivy, with camelCase/snake_case boundary matching — verifyToken finds verify_token), and optional semantic search against any OpenAI-compatible embeddings endpoint.
• Optional AI enrichment — genuinely optional: generate --enrich fills in missing descriptions via any OpenAI-compatible endpoint (Ollama, LM Studio, a cloud provider) and never overwrites an existing description; suggest-links proposes plausible missing relationships, advisory only.
• Deterministic architecture extraction — no AI required: graph layers (dependency depth), graph domains, graph communities (Clauset–Newman–Moore modularity clustering — verified by dogfooding to split an 18-crate workspace that connected-components collapses into one blob), graph patterns (Builder/Singleton/Factory/Visitor signals), graph features (REST endpoints, DB models by convention).
• CI & review: impact <ref-a> <ref-b> scores every changed concept by transitive-caller count (blast radius — M01's metric, productionized), public-API membership, and cycle participation; review renders a sticky-comment-ready Markdown report with --fail-on-risk gating and a ready-made GitHub Action.
• Validation built for CI: schema checks, dangling-link and orphan detection, duplicate identities, Calls/CalledBy asymmetry — with a --ci flag that hardens warnings into failures.
• Exports: HTML, paginated PDF, GraphML (Gephi/yEd), Obsidian vaults, and a two-way DITA bridge — round-tripped on its own 715-concept export with zero data loss.
• MCP server: okf-mcp exposes search, graph_callers, graph_callees, graph_api, graph_cycles, graph_modules, graph_path, and a composite explore. One-line registration:
  shell · register with Claude CodeCopy

  claude mcp add okf-rs -- /path/to/okf-mcp /path/to/project

  Because it speaks plain MCP over stdio, the same binary works with any MCP client — build the bundle once, every agent in your toolchain gets it. (M09 dissects this server and its token economics, including the ~400× per-query worked example.)

One more habit worth copying: every feature was dogfooded against okf-rs's own ~850-concept codebase — which caught a real DTD-handling bug in the DITA round-trip that a hand-written fixture would have missed. init also idempotently updates CLAUDE.md, AGENTS.md, and .github/copilot-instructions.md with a marked section pointing agents at the bundle, and the CI recipe okf-rs generate --no-cache && okf-rs validate --ci ensures a stale bundle never ships silently — a one-line preview of everything M11 stands for.

Semantic indexing vs structural graphs: leads vs answers

Cursor's built-in codebase indexing is the most widely deployed alternative, and it works on a different principle: vector embeddings. Your query is vectorized; the system returns code snippets ranked by similarity. Genuinely useful for exploration — "what files are related to authentication?" — when you don't know where to look.

But recall M02's structural blind spot, now in its sharpest form: semantic search doesn't understand relationships. It doesn't know that handleAuth() calls validateToken(), which imports from jwt_utils — it knows these functions contain similar language. So the AI receives leads — similarity-ranked hints it must verify by reading files one by one. A structural graph returns answers — definitive relationships, no verification reads. For code exploration, that's a fundamentally different information architecture, and it's why the two approaches complement rather than replace each other (M10 makes this a full three-layer design).

The cloud alternatives

• Gemini Code Assist (formerly Google Cloud Code): cloud-hosted understanding that handles enormous repositories — but your code is processed on Google's infrastructure. For data-sovereignty environments, that's disqualifying regardless of quality.
• Sourcegraph: powerful universal code search and browsing; requires server deployment, indexer configuration, and maintenance. Right for organizations needing a shared platform; heavy for individuals.
• GitHub Copilot's codebase indexing: limited beta, cloud-only, restricted rollout.

Against that landscape, the local tools' shared niche is precise: local-first, zero-configuration, structured-graph code intelligence — no servers, no API keys, no data transmission, and deterministic relationships instead of probability scores. Within the niche, the differentiation is the storage substrate and freshness model you've now seen from both sides.

The six comparison axes

Tools will keep launching. Evaluate every one of them on these six axes — each axis is a question with concrete consequences:

Walk it, step by step

The same repository through each tool in turn. Read it as a decision, not a ranking — the last step is the table that tells you which one your situation actually calls for.

Hands-on exercise: build the matrix for your own repo

No lab folder for this module — the exercise runs on your real project. Time: ~30 minutes.

1. Step 1 — profile the repo. Count files and languages (git ls-files | wc -l; look at extensions). Note whether you're above or below the ~500-file floor and which benchmark row (Gin? Django? VS Code?) your repo most resembles.
2. Step 2 — fill the six axes for your constraints. For each axis, write the requirement your environment imposes (e.g., "code cannot leave the machine" → axis 4 eliminates cloud tools immediately; "we live in PRs" → axis 2 favors okf-rs's git-diffable bundle).
3. Step 3 — pick and verify. Choose the tool the matrix points to. Install it, build the graph, and ask the three orderflow-style questions from the M04 lab ("who calls X", a path query, an impact query). ✅ Checkpoint: each answer verified against your own knowledge of the code.
4. Step 4 — record the honest number. Measure one real task with and without the graph (tokens or wall-clock). Compare against the benchmark row you predicted in Step 1. Keep this note — the capstone asks for it.

Stretch: run TWO tools on the same repo and diff their edge sets for one module. Where they disagree, determine which is right by reading the code — you'll usually find an INFERRED edge on one side and silence on the other, which is the provenance axis made tangible.

Knowledge check

Module summary

What we built on orderflow: nothing new in code this time — instead, a durable evaluation kit, plus your own repo's profile and (if you did the stretch) a two-tool edge diff that made provenance labeling concrete.

Next module preview: Track 3 begins. okf-rs generated Markdown-with-frontmatter files because a spec told it what shape agents can rely on. That spec — Google's Open Knowledge Format, one required field, a single page of conformance rules, and a surprising amount of design wisdom — is M06.

References

• CodeGraph — GitHub repository (MIT); 7-project benchmark methodology and results; auto-sync and route-recognition docs
• okf-rs — github.com/jyjeanne/okf-rs (releases, ROADMAP.md, pr-review.yml GitHub Action)
• Graphify — M04's references; BENCHMARKS.md for the vendor-vs-replicated context
• Sourcegraph, Gemini Code Assist, GitHub Copilot indexing — vendor docs (cloud/server alternatives)
• Course exercise: this module's embedded 4-step matrix exercise (no lab folder)