> ## Content Index
> Fetch the complete content index at: https://contextfirst.blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# Graphify - Knowledge Graphs for Monorepo Navigation
- URL: https://contextfirst.blog/graphify-monorepo-navigation/
- Published: 2026-09-15T13:00:00.000Z
- Updated: 2026-09-15T13:00:00.000Z
- Description: Query the graph before you grep
- Author: Iheatu Chris Wogu
- Tags: Field Notes, Engineering Management, Agentic Delivery, Learning Journey 2026

Agents and humans burn sessions grep-reading through monorepos and still miss cross-file seams. Wrong-file edits are expensive; onboarding without a map takes weeks. Brute-force exploration is the default because dependencies are implicit - until you index structure.

**Here's what this piece covers:** the leadership problem of search exhaustion, what commit `261c071` (2026-07-14) shipped as a portable kit, how I use `query` / `path` / `explain`, the named pattern, and three habits before you scale agent exploration across repos.

Part of the [Field Notes: agentic delivery](https://contextfirst.blog/field-notes-agentic-delivery/) series - structural navigation before token burn.

---

## 1\. The leadership problem

The anti-pattern is **search exhaustion** \- read every file because the graph of the system only exists in someone's head.

**Wrong:** "Use AI to search the repo."  
**Right:** "`261c071`: graphify `query` / `path` / `explain` \- AST knowledge graph first; grep only when the graph is insufficient."

Agent sessions that skip structure pay twice: token cost and wrong edits. Leads pay a third time in review.

---

## 2\. What the git history shows

On **2026-07-14**, commit `261c071` \- *Add Graphify setup documentation and portable install kit* \- made adoption copyable:

| Artifact                    | Role                                            |
| --------------------------- | ----------------------------------------------- |
| docs/graphify/              | README, guide, new-computer setup, agent prompt |
| tooling/graphify-setup-kit/ | install.sh / .ps1, rules, .graphifyignore       |
| Cursor rule                 | Query graph before Read/Grep/Glob               |

Later adoption spread into github-analysis, Planning, and consumer monorepos. Combined footprint across four indexed monorepos: **\~42,400 nodes** / 6,350 files (derived sum of local `GRAPH_REPORT` snapshots - light verify today: websites 12,652 + global-services 24,417 + global-user-services 3,549 + Planning \~2,088 ≈ \*\*42.7k\*\*). Exploration cost reduction of **50×+** vs brute-force file reads is **team-estimated** \- confirm methodology before treating it as a measured KPI.

flowchart TD Q\[Question about the codebase\] --> G\[graphify query / path / explain\] G -->|scoped subgraph| A\[Read exact files\] G -->|insufficient| R\[Grep / Glob fallback\] R --> A A --> E\[Edit with seam context\]

Daily habit encoded as a rule, not a suggestion:

```bash
# AST-only refresh - no LLM, no API cost
graphify update .

# Structural questions first
graphify query "How does HTML export reach the data cache?"
graphify path "export_html_report" "load_snapshot"
graphify explain "spec-driven"
```

---

## 3\. What I built

**Portable setup kit** \- install Graphify on a new machine or consumer repo without inventing process. Artifacts stay local and gitignored; only pointers and tooling live in Git.

**Query surface** \- `graphify update .` builds/refreshes the AST graph; `query` returns a scoped subgraph (including INFERRED cross-file edges); `path` connects two symbols; `explain` shows a node and neighbors. Optional `graphify-out/wiki/` and `GRAPH_REPORT.md` for orientation.

**Adoption pattern** \- Cursor `beforeSubmitPrompt` hook refreshes the graph; `.graphifyignore` excludes data/cache dumps; skills (`graphify`, `graphify-search`) keep agents honest about search order.

What broke: a **stale graph is worse than none** \- it points at deleted symbols. Rebuild after refactors (`graphify update .`, `--force` when the graph legitimately shrinks). Kit doc duplication later forced token compression (Index Protocol - later in the series).

---

## 4\. Named pattern: query graph before grep

> **Query graph before grep** \- AST knowledge graph for navigation; `query` / `path` / `explain` before search exhaustion.

| Command            | When                      | Decision it supports         |
| ------------------ | ------------------------- | ---------------------------- |
| graphify update .  | After edits / pull        | Is the map current?          |
| graphify query     | Any architecture question | Which subgraph matters?      |
| graphify path A B  | Seam / dependency risk    | How does A reach B?          |
| graphify explain X | Onboarding / naming       | What surrounds this concept? |

**What broke:** treating Graphify as evangelism. The mechanism is cheaper context for the same question you were going to ask with grep - measure time-to-first-correct-file, not tool enthusiasm.

---

## 5\. What I'd do as a lead

Three habits - steal one this month:

1. **Index one monorepo per quarter** \- start with highest-churn. Portable kit first; custom process never.
2. **Require `graphify query` in agent exploration rules (`AGENTS.md` / Cursor rules).** Make grep the fallback, not the default.
3. **Measure time-to-first-correct-file on agent tasks.** If the graph does not move that number, fix adoption or freshness - do not celebrate node counts alone.

---

### Further reading

- [Field notes: agentic delivery](https://contextfirst.blog/field-notes-agentic-delivery/) \- series intro
- Previous: [Invisible Unicode - markdown as an attack surface](https://contextfirst.blog/invisible-unicode-markdown-attack-surface/)
- agentic-framework anchor: commit `261c071` · 2026-07-14 · `docs/graphify/README.md`

---

![Iheatu Chris Wogu](https://avatars.githubusercontent.com/u/3457705?s=176&v=4)

## About the author

**Iheatu Chris Wogu** is an engineering manager focused on launch programs, honest engineering metrics, and **engineering-led, agent-accelerated** delivery - researching where work queues up when agents widen dev output, then building proof, gates, and measurement that scale.

Field notes live on [First Context](https://contextfirst.blog/). Values treatise: [engineering manager values](https://contextfirst.blog/engineering-manager-values/).

**LinkedIn:** [linkedin.com/in/iheatu-chris-wogu](https://www.linkedin.com/in/iheatu-chris-wogu/?ref=contextfirst.blog)