Graft builds a queryable code graph for AI coding agents. Here's how it works, how to install it, and how to use it to trace bugs across files.
What problem is Graft trying to solve? #
AI coding agents waste a lot of time rediscovering things they should already know. Ask an agent for a small fix and it often burns several minutes reading files, following imports, and reconstructing how the project fits together, only to repeat much of that work on the next task in the same session. Graft is an open source tool that addresses this by building a code graph: a structured map of functions, imports, and the connections between them, that an agent can query directly instead of re-reading the whole codebase from scratch.
Instead of grepping for a keyword and hoping the match is relevant, an agent (or a developer) can ask Graft where something is implemented, what functions live in a given file, or which parts of the project call a specific function. That last capability matters more than it sounds. Most real coding tasks aren’t about finding one match, they’re about tracing a path: if you change a permissions function, you need to know every service that depends on it, and if a feature misbehaves, you need to follow the chain that produced the bug.
How does Graft actually work? #
Graft operates in two layers, and the distinction matters for both cost and setup complexity.
Everyone else built a construction worker.
We built the contractor.
One file at a time.
UI, API, database, deploy.
The structural layer uses tree-sitter to parse code and extract functions, imports, and the edges connecting them. This layer requires no AI provider key at all. You can build the graph and run queries against it with zero API cost, because it’s static analysis, not model inference.
The deep layer is optional and adds AI-generated summaries and concept nodes on top of the structural graph. This layer does call your configured model provider, so it can incur API costs depending on which provider you use.
For most day-to-day use, the structural layer alone is enough to give an agent useful context: where things live, what calls what, and a quick skeleton of a file’s functions without dumping every line of source into the conversation.
Graft is MIT licensed, and the structural graph doesn’t need a separate database server. It stores its generated files in a .graft folder inside your project and adds that folder to .gitignore automatically, since the graph can always be regenerated from the source code.
One important cost distinction: Graft queries on the structural layer are free, but that doesn’t make your coding agent free. If your agent or underlying model charges for usage, those costs are entirely separate from whatever Graft itself costs to run.
How do you install and set up Graft? #
Graft is distributed as a CLI package and can be run via npx with the @nanonets/graft package name. It requires Node 20 or newer. The version tested for this workflow was 0.18.0.
The basic setup:
- Make sure you’re running Node 20+.
- Run Graft via
npx @nanonets/graft(pin a version if you want reproducibility). - Inside your code repository, run
graft build. No provider key is needed for this step since it’s the structural layer. - Optional telemetry can be disabled if you don’t want it running in the background.
Once built, Graft produces a set of nodes (functions, files, etc.) and edges (the relationships between them) based on your source files. For reference, a small nine-file JavaScript fixture used in testing produced 29 nodes and 66 edges, a number that reflects the size of that particular test project rather than any general benchmark.
How do you query the graph once it’s built? #
Graft exposes a handful of commands that are useful once the graph exists:
graft map: gives an overview of the codebase structure.- Targeted questions with
--source: for example, asking where a specific permission check happens returns the relevant functions and their file locations, including the actual source excerpts. graft skeleton: run against a specific file to list function signatures without pulling in full function bodies, useful for getting a quick sense of a file’s API surface.- Caller tracing with a depth flag : asking which parts of the project call a given function, with a depth parameter controlling how many hops out from that function to follow.
graft check: reports whether the graph is stale relative to the current source, and identifies which files changed.
These queries are deterministic retrieval, not model calls. Asking “where is X implemented” doesn’t cost an additional inference request, it’s a lookup against the structural graph already built.
How does this help trace an actual bug? #
Other agents ship a demo. Remy ships an app. #
Real backend. Real database. Real auth. Real plumbing. Remy has it all.
The clearest illustration of Graft’s value is in tracing a broken permission check across files, which is exactly the kind of multi-file relationship problem that plain keyword search handles poorly.
In a demonstrated example, a document service had a policy that viewers could read shared documents but not export them, while editors and owners could do both. A failing test showed a viewer successfully exporting a document that should have returned a 403 error.
Querying Graft for “where are export permissions checked” returned the export function, a dedicated export permission helper, the route handler, and the document- function together, a useful cluster of related code for that specific question. Running graft skeleton on the permissions file listed out read, edit, and export permission checks without needing to read every function body.
The key insight came from tracing callers. Asking which parts of the codebase call the export permission helper returned only the test file, not the export service itself. That’s the tell: the permission helper existed and was correctly tested in isolation, but the actual export code path never called it. Following the source confirmed it: the export service loaded the document through a read-access check (which viewers pass), then generated the CSV without ever checking the stricter export permission. The graph didn’t fix the bug, but it pointed directly at the disconnect between “policy exists” and “policy is enforced.”
After the fix (importing the permission helper into the export service and rejecting unauthorized requests), running graft check detected the graph was stale, and a follow-up query triggered an automatic refresh limited to the changed file. The caller trace then showed the export function correctly connected to the permission helper, confirming the fix closed the gap. All nine tests passed afterward.
What are Graft’s limitations? #
Static analysis has real limits, particularly around dynamic behavior that isn’t visible from parsing code structure alone, and language support varies in depth across different codebases. The graph is a useful starting point for investigation, but ambiguous results still require reading the actual code.
Automatic refreshing (triggered via graft check) updates the structural graph, but it does not regenerate paid AI summaries from the deep layer every time. If you’re relying on the deep layer’s AI-written summaries, you need to verify they actually ran with your configured provider, since a successful command doesn’t guarantee that step executed.
Some Graft outputs include token-saving estimates, comparing the context returned against reading the full covered files. These are estimates from the tool itself, not a measurement of an actual session’s total token usage. The maintainers report benchmark figures of 42% fewer tokens and 60% less time in their own controlled testing, but those numbers come from their specific benchmark setup and shouldn’t be assumed to generalize to every project or workflow.
Is Graft worth trying? #
Remy is new. The platform isn't. #
Remy is the latest expression of years of platform work. Not a hastily wrapped LLM.
For teams whose AI agents repeatedly need to reason about relationships spanning multiple files, permission checks, service boundaries, shared utilities, Graft’s structural layer is low-risk to try: no provider key, no server, no cost beyond the setup time. Start there, run a few targeted queries against your actual codebase, and judge whether the retrieval quality improves your agent’s starting point before considering the optional (and cost-incurring) deep layer with AI-generated summaries. It’s not a replacement for tests or code review. A graph showing a new function call doesn’t prove the implementation is correct, it just shows you where to look. Pairing graph-based investigation with your existing test suite remains the more reliable workflow.
Frequently Asked Questions #
Does Graft require an API key to use?
No, the structural layer, which uses tree-sitter to parse code and build the graph of functions and their connections, works without any AI provider key. Only the optional deep layer, which adds AI-generated summaries, calls a model provider and can incur costs.
What version of Node does Graft need?
Graft 0.18.0 requires Node 20 or newer.
Does Graft store data in a separate database?
No. The structural graph is stored in a .graft folder inside your project directory, which is automatically added to .gitignore since it can be regenerated from source at any time.
Can Graft automatically update the graph after code changes?
Yes. Running graft check reports whether the graph is stale and which files changed. Subsequent queries can trigger a refresh limited to the changed files rather than requiring a full rebuild.
Is Graft tied to any specific AI coding agent?
No. Graft is a standalone CLI tool with an MCP server available for integration. It can be invoked by any agent capable of running command-line tools or connecting via MCP, it isn’t limited to one particular coding assistant.