I Built an AI Code Investigator That Uses a Graph Instead of Guessing
Building CodeTrace for Graph Hacks 2026 with WeMakeDevs and FalkorDB
When we ask an AI model to explain a codebase, it can usually explain the code we show it. The harder question is what happens when the answer depends on code spread across multiple files.
Suppose I change a function. Which other functions might be affected? Which files depend on it? Where should I start investigating a potential bug?
Reading individual files is not enough. I need to understand how the code is connected.
That was the idea behind CodeTrace, a graph-powered code investigation agent I built for Graph Hacks 2026, the WeMakeDevs × FalkorDB hackathon.
- Live demo: https://code-trace-alpha.vercel.app
- Source code: https://github.com/brijesh025/codeTrace
The problem I wanted to solve
Developers often struggle not because they cannot read code, but because understanding a real project means moving between files, tracking dependencies, following function calls, and figuring out which components are relevant to a change.
An LLM can help, but putting more code into a prompt doesn't automatically give it a reliable understanding of how those pieces connect.
I wanted CodeTrace to work differently. Instead of asking the model to figure everything out from a block of text, I wanted to give it a structured representation of the codebase that it could investigate.
That is where FalkorDB comes in.
Why FalkorDB?
I didn't want to use a graph database merely to draw a nice graph on the screen. The graph had to do actual work.
CodeTrace represents a codebase through entities such as repositories, files, functions, classes, and modules. Relationships describe how those entities connect:
-
CONTAINS— how repository and source entities are organized. -
IMPORTS— which modules import other modules. -
CALLS— function calls the extractor can resolve with sufficient evidence. -
DEPENDS_ON— supported dependency relationships.
When someone asks what could be affected by a change, I want the system to follow available connections, retrieve relevant evidence, and explain why a component is worth investigating.
FalkorDB is the graph-reasoning layer behind that workflow, not just a visualization database.
How CodeTrace works
1. Start with a public GitHub repository
The user provides a public GitHub repository URL and an investigation question. CodeTrace validates the URL and clones the repository into a temporary workspace. The ingestion process is designed not to execute code or lifecycle scripts from the repository being analyzed.
2. Extract the code structure
I evaluated FalkorDB's CodeGraph project before deciding how to implement extraction. The existing JavaScript analysis path did not provide all the TypeScript, TSX, JSX, and dependency evidence required by my initial design.
Rather than forcing an imperfect fit, I chose to build a project-owned extraction layer using Tree-sitter. The extractor parses supported source files and produces normalized entities, source locations, and relationships. The implementation supports TypeScript/JavaScript, Python, Java, C, C++, and Go.
The goal isn't to pretend every relationship can always be resolved. When a call is ambiguous or dynamic, CodeTrace should avoid inventing a relationship. A missing edge is better than one that misleads the investigation.
3. Store evidence in FalkorDB
After extraction, the worker loads entities and relationships into FalkorDB. Stable identifiers and repeatable writes help make indexing idempotent, while source paths and line ranges provide evidence for later investigation.
4. Let the agent investigate
The LLM does not receive unrestricted access to the database. CodeTrace exposes a bounded set of tools for finding code entities, traversing dependencies, finding callers, following relationships, and retrieving source evidence.
The model selects tools, interprets results, and composes an explanation. The backend validates tool arguments and controls the graph queries.
The goal is to combine two strengths: graph queries establish the available relationships, while the LLM turns retrieved evidence into an understandable report.
5. Return an actionable report
The intended result includes a summary, ranked potentially affected files and functions, supporting relationship paths, source locations, a prioritized investigation checklist, and uncertainty notes when evidence is incomplete.
The architecture
Public GitHub Repository
|
v
Safe Repository Ingestion
|
v
Tree-sitter Extraction
|
v
Normalized Code Entities
and Relationships
|
v
FalkorDB
|
v
Bounded Investigation Tools
|
v
LLM Agent
|
v
Evidence-backed Investigation
|
v
UI
The implementation uses Next.js and TypeScript for the frontend, a Node.js and TypeScript backend, Tree-sitter for extraction, FalkorDB for graph storage and traversal, and a configurable server-side LLM provider.
What made the build interesting?
The most useful part of this project was deciding where the model should be trusted and where deterministic code should take control.
I didn't want the model generating arbitrary Cypher queries or fabricating function calls and source locations because a relationship seemed plausible. That pushed me toward fixed investigation tools, bounded queries, explicit evidence, stable graph identities, and a distinction between retrieved facts and model-generated interpretation.
Evaluating existing code also reinforced a lesson: a library can be useful and still be the wrong fit for a particular contract. Testing the implementation matters more than assuming its advertised capabilities match the requirements.
What is still difficult?
CodeTrace is not a perfect representation of every possible codebase. Dynamic dispatch, runtime-generated behavior, reflection, and ambiguous calls can make relationships difficult to resolve confidently through static extraction alone.
Large repositories also introduce practical constraints: cloning, parsing, indexing, model latency, and inference quotas all need to be handled carefully. These are areas I would continue improving through tests on real repositories and investigation scenarios.
What I learned from building with FalkorDB
First, relationships can be more useful than another pile of retrieved text. When a question depends on how parts of a codebase connect, a graph provides explicit structure the agent can traverse.
Second, evidence needs to remain separate from interpretation. The graph and extraction layer should establish which relationships are supported. The LLM should explain what the evidence means and acknowledge gaps.
Third, the graph must be central to the product. If removing FalkorDB leaves the investigation workflow essentially unchanged, I haven't made good use of a graph database. In CodeTrace, the graph is intended to drive dependency traversal, caller discovery, evidence-path retrieval, and investigation prioritization.
Try CodeTrace
CodeTrace is my entry for Graph Hacks 2026, organized by WeMakeDevs in collaboration with FalkorDB.
- Live demo: https://code-trace-alpha.vercel.app
- GitHub repository: https://github.com/brijesh025/codeTrace
- Hackathon: https://www.wemakedevs.org/hackathons/falkordb
The idea is simple: when investigating a codebase, don't make the model guess how everything connects. Give it a graph it can query, evidence it can trace, and enough context to explain where a developer should look next.
I'm excited to keep improving that approach and see how far graph-backed code investigation can go.
Disclosure: I used AI coding assistance during development. The project's architecture, implementation choices, validation, and technical decisions remain my responsibility.
