[ COMPARE · CODE GRAPH FOR AGENTS ]
Give your AI coding agent a map of the codebase
An AI coding agent works the way you would on day one of a new repo: it greps for a name, opens a few files, and guesses at how they connect. That guessing is where it breaks things. A local code graph fixes the input. GraphTrail indexes your repo once into a small SQLite graph of symbols, imports, and call edges, then answers structural questions, callers, callees, impact, and blast radius, over a CLI or a read-only MCP server. The agent asks "who calls this and what does my edit reach" before it writes a single line, instead of finding out after.
[ 01 · THE PROBLEM ]
Agents read code as flat text. They grep for a symbol, get a list of line matches that mixes real call sites with comments and unrelated names, open whatever looks relevant, and infer the rest. The structure that a compiler or an IDE has, this function is called from these three places, this import is dead, changing this signature touches that module, is not available to the agent. So it edits with an incomplete picture.
The failure mode is concrete. The agent renames or changes a function, misses a caller that grep did not surface cleanly, and ships a break it cannot see in its own context window. More text in the window does not fix this. The missing thing is not more lines, it is the edges between them.
[ 02 · GRAPH vs GREP vs SEMANTIC SEARCH ]
These are three different tools for three different questions. The honest comparison is on capability, not on which one is "best." Use the one that matches the question you are asking.
| Capability | grep / ripgrep | Semantic / embedding search | GraphTrail (code graph) |
|---|---|---|---|
| Find a string or identifier by text | Yes, this is what grep is for | Yes, plus near-matches | Yes, full-text search over indexed symbols |
| Find code that is similar in meaning | No, text only | Yes, this is the point of embeddings | No, not on its own |
| List every caller of a function | Approximate, name matches include comments and unrelated text | No, similarity is not a call edge | Yes, resolved from the call graph |
| List what a function calls | No, you read the body by hand | No | Yes, callees from the graph |
| Estimate blast radius before editing a symbol | No, you trace it manually | No | Yes, impact walks the edges |
| Works with no index or setup | Yes, zero setup | No, needs an embedding index | No, needs one indexing pass |
| Runs locally, no network | Yes | Depends, some embed via a hosted API | Yes, default binary makes no network calls |
Grep and ripgrep are excellent at what they do and need no setup, reach for them first for a literal string. Semantic search is the right call when you are looking for code by meaning rather than by name. GraphTrail is the structural layer, and it is complementary, not a replacement. An optional adapter blends Code Search embedding hits with graph centrality so a single query can return both "similar" and "connected" results.
[ 03 · WHEN TO USE IT, WHEN YOU DON'T ]
Use a code graph when
Your agent edits a codebase large enough that no one holds the call structure in their head. You want it to check callers, callees, and impact before a refactor or a signature change. You want structural answers that grep approximates and semantic search cannot give: who calls this, what does it reach.
You do not need this when
The codebase is tiny. If the whole project is a handful of files an agent can read end to end, grep is fine and a graph is overhead you do not need. The relationships are already obvious because they all fit in one window. Reach for the graph when the repo outgrows that, not before.
[ 04 · FAQ ]
Does this replace grep or semantic code search?
No. Grep is still the fastest way to find a literal string, and semantic search is still the right tool for "find code that does something like this." GraphTrail answers a different question: who calls this, what does it call, and what does a change here reach. It is structural, and it pairs with semantic search through an optional adapter that blends embedding hits with graph centrality.
How does an agent actually query it?
Two ways. Over the CLI (callers, callees, impact, context, search) or over a read-only MCP server that exposes those same operations as tools. The MCP server opens the SQLite database read-only, so an agent can never mutate the graph while reading it.
Which languages are supported?
Python, TypeScript/JavaScript, Rust, and Go today. Symbols, imports, and call edges are extracted from the tree-sitter AST per language, and the graph shape is identical across all of them.
[ 05 · GET STARTED ]
GraphTrail is a Rust CLI, MIT licensed. Install it, index a repo, and point your agent at the CLI or the read-only MCP server.