Graft: A local markdown graph that gives coding agents a persistent map of your codebase

The problem Graft targets: agents that forget the map

Every coding session, an agent like Claude Code starts blind. It greps for a term, opens a file, follows an import, backs out, and tries again. By the time it understands the code, it has spent dozens of tool calls and thousands of tokens. The next task repeats that exploration from zero, and the next teammate starts from zero as well. Graft's README frames this as a human versus agent asymmetry: humans onboard to a codebase once, agents onboard every single time. The tool's core bet is that a persistent, human-readable map of the codebase can eliminate most of that repeated discovery. The intended user is a developer or team running AI coding agents on a large existing codebase, not someone starting a greenfield project where the code is small enough for the agent to hold in context.

What Graft actually writes: linked markdown, not an index

Graft builds a folder named `graft/` in your repo. Inside it are markdown files, one node per system, API, or concept. Each node contains a plain-English explanation of what that part does and how it connects to the rest, the way a senior engineer would describe it. Crucially, the README insists there are no embeddings, no similarity search, and no index to keep warm. The graph is a set of linked files that your agent opens, greps, and follows, exactly like any other file in the repository. That design choice has two consequences. First, the agent does not need a special retrieval mechanism; it just reads markdown. Second, the graph is transparent: you can open any node and see exactly what the agent will see. The trade-off is that the graph is only as good as the explanations generated during `graft build`. If those explanations are vague or wrong, the agent will trust a misleading map.

How the graph gets built and what runs where

The README describes a code graph built with tree-sitter, which is a parser generator that can handle many languages. The repository topics include `tree-sitter` and `code-graph`, and the README has a section on supported languages, though the truncated material does not list them. The build process extracts symbols and relationships from your source, then generates the markdown nodes. The key architectural point is that the graph is built locally on your machine. There is no daemon, no background service, and no re-indexing to remember. The README says the graph is just files, and it is meant to be treated like `node_modules`: a local, regenerable cache that you do not commit. This means the build cost is paid once per checkout, and each teammate runs `graft build` to generate their own copy. The graph is not shared through version control, only the wiring in `.claude/` is committed.

Setup: two commands and a dry-run flag

Installation is straightforward. You run `npm install -g @nanonets/graft` once, then `graft init` in your repository. The init command asks which coding agents to wire up, builds the `graft/` folder, and drops a statusline and hooks into `.claude/`. From the next session, Graft rides along in Claude Code, pulling matching nodes into each prompt and rebuilding the graph in the background after every turn. The README emphasizes that nothing is written until you choose. You can run `graft init --dry-run` to see every file it would touch first, or `graft init --agents claude` to skip the prompt. The build command `graft build` automatically adds `graft/` to your `.gitignore`. If you prefer not to install globally, `npx @nanonets/graft init` works the same way. For a team, you commit the `.claude/` wiring, and each teammate runs `graft build` to generate their own graph.

The claimed benchmark: fewer calls, lower cost, better correctness

The README presents a table comparing cold Claude Code against Claude Code with Graft. It claims a 46% reduction in tool calls, 42% token savings, 60% time savings, and a correctness improvement from 54% to 66% on what appears to be an internal benchmark. The README also mentions SWE-bench Verified as a section, though the truncated material does not include the actual numbers. These figures are vendor claims, not independent measurements. I have not run this tool, and the README gives no methodology details such as the number of tasks, the repository set, or how correctness was scored. Treat the headline as a directional signal, not a guarantee. The mechanism is plausible: if an agent can read a node that explains a subsystem, it should skip several grep-and-open cycles. But the magnitude depends heavily on the quality of the generated nodes and the complexity of your codebase.

Agent integration: deep for Claude Code, MCP for the rest

The README lists two integration paths. For Claude Code, there is a deep integration where Graft drops hooks and a statusline into `.claude/`, and the graph is rebuilt in the background after every turn. That means the agent gets fresh nodes on the next prompt without manual re-indexing. For other agents like Cursor, Codex, and Gemini, the integration is via an MCP server, which is a standard protocol for giving agents access to external tools. The MCP server presumably exposes the graph as resources or tools that the agent can query. The README does not detail how the MCP server behaves, but the key difference is that deep integration is automatic, while MCP requires the agent to actively request the graph. That distinction matters: an agent that does not know to call the MCP tool will not benefit, whereas the Claude Code hooks inject context without the agent asking.

CLI tools beyond the graph: grep, map, and viz

Graft ships with additional CLI commands. `graft grep` and `graft map` are for search and orientation, letting you find nodes and see how they connect. `graft viz` visualizes the graph. These are useful for humans too, not just agents. You can inspect the graph before letting an agent rely on it, which is a practical way to sanity-check the generated explanations. The README also mentions monorepo and multi-repo folder support, though the details are truncated. That suggests Graft can handle a workspace with multiple packages, which is where a single flat graph would fail. The presence of these commands indicates that Graft is not a black box; you can interact with the graph directly.

Limitations and failure modes: staleness, language coverage, and trust

The biggest limitation is that the graph is a static snapshot. The README says it rebuilds in the background after every turn in Claude Code, but that rebuild is asynchronous. If you edit a file and immediately start a new task, the agent might read a node that describes the old code. The graph is also only as accurate as the last build. For a fast-moving codebase with frequent refactors, the graph could lag behind reality. The README does not describe any mechanism for detecting staleness or invalidating nodes. Another limitation is language coverage. The README lists supported languages, but the truncated material does not include them. If your codebase uses a language not in that list, Graft will not build a useful graph. Finally, the graph is generated by an AI model, presumably, and the README claims it produces real explanations, not symbol dumps. That means the quality is probabilistic. A wrong explanation could mislead an agent more than no explanation at all.

Alternatives: context engineering versus retrieval

The closest alternative is a retrieval-augmented generation (RAG) tool that embeds your code and performs similarity search on each query. Tools like `continue` or `cursor`'s built-in codebase indexing use embeddings to find relevant snippets. The difference in approach is fundamental: RAG systems maintain a vector index that requires a warm service or a local database, and they return raw code snippets, not explanations. Graft deliberately avoids embeddings and instead writes linked markdown that an agent can read like any file. That means Graft's retrieval is not semantic; it relies on the agent following links between nodes. Another alternative is simply giving the agent a well-written `CLAUDE.md` file at the repo root, which is a manual approach. Graft automates the generation of that kind of context but at a finer granularity. The trade-off is that a RAG system can answer arbitrary queries, while Graft only knows what is in the nodes. For a novel question about a part of the code that the graph did not explain well, the agent will fall back to exploration anyway.

Maintenance, telemetry, and license

Graft is MIT licensed, which means you can use, modify, and embed it freely, provided you retain the copyright notice. The repository is written in TypeScript with strict mode. The README mentions a `TELEMETRY.md` file and a badge that calls the telemetry anonymous and opt-out. That means the tool collects anonymous usage data by default, and you must actively opt out. The exact mechanism is not in the README, but you should check that file before deploying in a sensitive environment. Maintenance cost is low on a day-to-day basis because the graph is regenerable. You do not commit it, so there is no merge conflict risk. The cost appears when your codebase changes significantly: you or your CI must run `graft build` to refresh the graph. The README says the Claude Code integration rebuilds in the background after every turn, which reduces manual overhead, but for other agents you may need to trigger builds manually. There are no releases listed, so the project may be early in its lifecycle, and the API could change.

Editorial conclusion

Adopt Graft if you work in a large TypeScript, Python, or other supported codebase where coding agents repeatedly waste tool calls re-discovering structure, and if you accept that the graph is a local regenerable cache that each teammate must rebuild. Do not adopt it if you need real-time symbol-level accuracy, if you cannot tolerate occasional stale nodes after edits, or if your codebase uses many unsupported languages. Before committing, run `graft init --dry-run` to inspect every file it would touch, verify that your language is in the supported list, and check the TELEMETRY.md opt-out if you care about anonymous usage data. The graph's value depends entirely on the quality of its explanations, so test it on one module first and judge whether the node text matches how your team thinks about the code.

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. trailhq/Graft on GitHub