Published on March 6, 2026 • 10 min read
A few months ago I was watching an AI agent "fix" a bug in one of my TypeScript services. It read the file, rewrote the function, and marked the task done. Clean. Confident. Completely broken — because it had no idea that three other modules called that function with assumptions baked into the old signature.
That's the grep problem. Every AI coding tool, at its core, still searches for text. It finds the word you asked about and gives you lines around it. What it doesn't give you is the graph: what calls this, what this calls, what breaks if you change it.
For small scripts and throwaway tools that's fine. For a production codebase with 3,000+ symbols and a decade of accumulated decisions, it's a liability.
Grep and glob are fast. They're good at finding where a symbol appears. But they answer the wrong question.
When an agent asks "what is processPayment?" the useful answer isn't "here are 12 files that mention it." The useful answer is:
CheckoutService.submit() and SubscriptionRenewal.run()PaymentGateway.charge() and LedgerService.record()That's architectural context. Without it, agents make locally correct but globally destructive changes. They rename a parameter without knowing it's destructured in 6 places. They add a return value without realizing callers don't check it. They extract a function without noticing the execution flow depends on call order.
The fix isn't better prompts. It's better data.
A knowledge graph for code maps three things:
With that graph indexed and queryable, an agent can answer questions that grep fundamentally cannot:
createUser?"AuthContext interface?"fetchProjects and what each caller does with the result."This is what I started building toward when I set up GitNexus in my portfolio workspace.
GitNexus is a local-first code intelligence engine. No cloud service, no subscription, no data leaving your machine. You run one command:
npx gitnexus analyze
It walks your codebase, parses every file, extracts symbols and relationships, builds the graph, and exposes it through an MCP server that AI agents can query in real time.
For my portfolio workspace — a multi-repo TypeScript/Python monorepo — the output after a full analysis was:
Those numbers aren't impressive on their own. What matters is that every agent session now starts with that graph queryable rather than having to re-derive it from raw text searches.
The MCP server exposes structured tools that agents call during their work. Instead of grep -r "handleSubmit" src/, an agent can query:
gitnexus://repo/freelance-portfolio/symbol/handleSubmit
→ defined in: src/components/ContactForm.tsx
→ calls: validateForm(), submitToAPI(), showToast()
→ called by: ContactPage (direct), TestimonialForm (via ref)
→ execution flow: user-input → validation → API → notification
Or for impact analysis before a change:
gitnexus://repo/freelance-portfolio/impact/AuthContext
→ 14 components import this
→ 3 hooks depend on its shape
→ 2 middleware functions read from it
→ changing the interface affects these 19 entry points
That's the difference between an agent guessing and an agent knowing.
GitNexus is one layer. I use it alongside several others that compound the benefit.
CLAUDE.md — 17 rules for agent behavior
This file is loaded automatically by Claude Code and defines how agents operate in my workspace. It covers things like mandatory git worktree isolation (each agent gets its own working directory), pattern discovery order (same file first, then adjacent files, then module-wide), and the validation gates that must pass before any commit. Without this, agents would make technically correct changes that don't fit the codebase.
AGENTS.md per directory
Each repo and significant subdirectory has its own AGENTS.md with rules specific to that area. The backend Python repo has different conventions than the Next.js frontend. Agents read the nearest AGENTS.md before touching anything in that directory.
Pattern contracts in docs/contracts/
Before orchestrating parallel agents across a feature, I run a pattern discovery pass that writes concrete contracts: exact import patterns, naming conventions, component structure templates, API endpoint shapes. Agents get these injected into their prompts so they match the existing codebase instead of inventing their own conventions.
PreToolUse hooks enriching searches
Claude Code supports hooks that fire before tool calls. I use a PreToolUse hook on search operations to automatically enrich queries with GitNexus context — so when an agent searches for a symbol, it gets the graph data alongside the text matches without having to explicitly ask for it.
This stack earns its complexity in specific situations:
Complex enterprise codebases where a change in one module has non-obvious downstream effects. If your codebase has more than ~50 files with meaningful interdependencies, text search alone will miss things.
Multi-repo projects where a type change in a shared library breaks consumers in separate repos. GitNexus can index multiple repos and trace cross-repo relationships.
Unfamiliar codebases you've inherited or are onboarding into. The graph gives you a map before you start touching things.
Parallel agent execution where multiple agents work on different parts of the same codebase simultaneously. Without shared architectural context, they'll make conflicting assumptions. With GitNexus indexed and the pattern contracts written, they all operate from the same ground truth.
I want to be straight about this: most projects don't need it.
If you're building a small script, a single-file tool, a weekend project, or a prototype where the whole codebase fits in your head — this setup adds friction without benefit. Grep works fine. So does just reading the files.
The overhead of npx gitnexus analyze (which takes a few seconds to a couple minutes depending on codebase size), maintaining the CLAUDE.md rules, writing AGENTS.md files per directory, and keeping pattern contracts current — that's real work. It only makes sense when the cost of an agent making a blind, structurally broken change is higher than the cost of maintaining the index.
For a production portfolio with an AI chat layer, RAG backend, and CI/CD pipeline across multiple repos, it makes sense. For a personal blog, it doesn't.
GitNexus isn't the only approach. A few others I've looked at:
Sourcegraph — mature, well-funded, works at scale. Has a cloud service and enterprise pricing. Better fit for large teams than solo freelancers.
tree-sitter — low-level parser library that many tools build on. If you want to build your own tooling rather than use an existing engine, this is a good starting point.
Language Server Protocol (LSP) — editors like VS Code already have symbol graphs via LSP. Some MCP bridges expose LSP data to agents. Worth exploring if you're already in VS Code and want the graph without a separate tool.
What drew me to GitNexus specifically was the zero-server local model and the MCP-native design. It was built to be consumed by AI agents, not retrofitted for them.
The problem isn't that AI agents are bad at reading code. They're genuinely good at it. The problem is that reading code and understanding a codebase's architecture are different things.
Text search answers "where is this thing?" Knowledge graphs answer "what is this thing's role in the system?" Those two questions have different answers, and the second one is what agents need to make changes that don't break things.
If your codebase is complex enough that you'd want a new developer to read architecture docs before touching anything — it's complex enough to benefit from giving your agents the same context in graph form.
Here's what I found works: index first, then implement. Run npx gitnexus analyze once, wire the MCP server into your agent setup, write the CLAUDE.md rules, and let the graph do the heavy lifting that grep was never designed for.
The agents still make mistakes. But they make fewer of the structurally blind ones.
Working on a complex codebase and thinking about agent-assisted development? Let's talk — I've been running this setup in production and I'm happy to share what's worked and what hasn't.