# Graft: Build a Context Graph to Speed Up Your Coding Agent

> Graft is a TypeScript CLI that builds a codebase context graph as linked Markdown files, so AI coding agents like Claude Code and Cursor stop re-exploring the same codebase on every task. The benchmark results from the project's own harness show 42% fewer tokens and 60% less time per session.

**trailhq/Graft** — Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

- Repository: https://github.com/trailhq/Graft
- Website: https://graft.nanonets.ai
- Stars: 9,427 · Forks: 865
- Language: TypeScript
- License: MIT
- Published: 2026-09-09 · Updated: 2026-09-09 · Language: en
- Canonical page: https://hysenlabs.com/projects/trailhq-graft

## The Exploration Cost That Repeats Every Session

Every time an AI coding agent starts a task in your repository, it begins from zero. It greps for a term, opens a file, follows an import, backs out, and tries another path. The README describes this as rebuilding a picture of a codebase the agent mapped an hour ago and then discarded. That rediscovery burns tool calls, tokens, and time before the agent has done anything productive.

Three properties make this costly. First, the cost is paid again for every task, regardless of how recently the agent explored the same area. Second, whatever the agent learned during one session disappears when the session ends. Third, each teammate and their agent start the same exploration from scratch.

Graft is a TypeScript CLI that addresses this by building the codebase understanding once and writing the result as a folder of linked Markdown files. It then wires those files into Claude Code, Cursor, Codex, Gemini, or any agent that reads files. The target audience is engineers who run AI coding agents regularly and want to eliminate per-session exploration overhead rather than pay for it repeatedly.

## Graph Structure: Nodes, Tree-Sitter, and Summaries

Graft's build process runs in two distinct phases. The structural phase uses tree-sitter, a deterministic parser, to map functions, classes, imports, and call relationships across the codebase. This phase requires no API key and takes roughly three milliseconds when nothing in the repository has changed. The result is a set of linked Markdown files in a graft/ directory, one node per system, API, or concept.

The deep phase writes plain-English summaries for each node, describing what a part of the system does and how it connects to the rest. This phase calls a language model and requires an API key. Graft is provider-neutral: the .env.example file lists the openai wire format, which covers OpenRouter, Fireworks, Groq, and any OpenAI-compatible endpoint, alongside native Anthropic support. The model is selected through three environment variables: GRAFT_PROVIDER, GRAFT_API_KEY, and GRAFT_MODEL.

The graph lives in graft/ and graft build adds that directory to .gitignore automatically. The README describes it as a regenerable local cache rather than something to commit. What gets committed and shared with teammates is the small wiring that graft init places in .claude/ and AGENTS.md. Each developer then runs graft build to generate their own local copy.

Each query also rebuilds the graph against the working tree structurally before it answers. The README notes this takes approximately three milliseconds when nothing moved, which means the graph reflects uncommitted edits as well as committed changes.

## Installing Graft and Wiring It into Claude Code

Graft requires Node 20 or newer. Install the CLI globally and run initialization from the root of your repository:

```bash
npm install -g @nanonets/graft   # install the CLI, once
graft init                       # build the graph + wire it into Claude Code
```

The init command asks which agents to wire up, builds graft/, and places a statusline and hooks into .claude/. After this, every subsequent Claude Code session starts with the context graph available. To see every file the command would touch before writing anything, use the --dry-run flag. To wire Claude Code specifically and skip the interactive prompt, pass --agents claude.

If you prefer not to install globally, npx @nanonets/graft init works the same way. To share the wiring with teammates, commit the .claude/ directory:

```bash
git add .claude && git commit -m "wire in graft"
```

Each teammate then runs graft build to generate their own local graft/ cache. The graft check command provides a local freshness signal for the current graph without triggering a full rebuild. The graft grep and graft map commands let you search and visualize the graph from the command line.

## What the Benchmark Measured and What It Did Not

The README publishes results from a controlled harness that ran three agent variants across 162 runs and two repositories using Claude Sonnet 5. The three variants were: cold (the agent explores from zero on each task), Graft (a bundle of relevant nodes injected up front via graft ask --source), and pull (graph tools available but nothing injected automatically). A separate Opus 4.8 judge scored correctness using a required-keyword floor, which prevented fast but wrong answers from winning on speed alone. Cost calculations used cache-aware pricing, with reads at approximately 0.1x and writes at 1.25x.

The results the README reports: 46% fewer tool calls, 42% fewer tokens, 60% less time, and correctness rising from 54% on cold runs to 66% with Graft. These are the project's own benchmarks, run by its authors on two specific repositories with one specific judge model. The task set, the choice of repositories, and the judge's required-keyword criteria all influence the numbers. Independent reproductions on different codebases have not been published as of the last push on 2026-09-27.

The benchmark design is described in enough detail to read critically. The pull variant, which uses tool calls to fetch graph data on demand rather than injecting it up front, represents a meaningful middle option for teams concerned about front-loading context on every session.

## Limitations and Cases Where Graft Does Not Fit

The deep build requires API calls to a language model, which costs both time and money for a large repository. The structural build alone, without the --deep flag, uses tree-sitter and runs fast, but graph nodes will contain structural data only and not the plain-English descriptions that let an agent understand what a subsystem does without reading its source code.

Graft does not encrypt or restrict access to its output. The graft/ directory contains Markdown files that describe your codebase's architecture and design in readable detail. On a shared machine or in a CI environment, that content is accessible to anyone with filesystem access. The repository includes a TELEMETRY.md file; teams in regulated environments should review it before deploying Graft.

Language support depends on available tree-sitter parsers. The package.json includes parsers for Go, Java, Kotlin, PHP, Python, Ruby, and TypeScript. Code in languages not covered by a parser will not be represented in the structural graph.

Finally, the tool offers little benefit for very small codebases that fit comfortably in a model context window without any graph preprocessing. If the agent can read all relevant code in a single pass, the build-once approach adds overhead with minimal upside.

## Graft Versus Repo-Packing and On-Demand Retrieval

The common alternative for giving an AI agent codebase context is a repo-packing tool such as repomix, which reads all files in a repository, concatenates them, and produces a single large text block for pasting into an AI chat window. This approach requires no setup and works for small codebases or one-off questions. The ceiling is the model context window: for large repositories, the packed output exceeds what fits, and every session repeats the same full scan regardless of which part of the codebase the task actually touches.

Graft works differently. It builds a graph once and then injects only the nodes relevant to a specific query. The agent receives a targeted summary of the relevant subsystem rather than a flat dump of the entire codebase. This keeps token use proportional to the task rather than to the repository size.

The tradeoff is explicit setup cost. Graft requires a build step, a provider API key for the deep pass, and occasional rebuilds when the codebase changes substantially. The pull variant, which exposes graph tools for the agent to call when it needs them, trades the up-front injection cost against selective on-demand fetches. A repo-packing approach has no build cost but pays a larger per-session context cost on every run.

## License, Telemetry, and Upgrade Considerations

The package.json declares version 0.20.0 under the MIT license. The MIT license places no restrictions on commercial use or redistribution. The last push to the repository was on 2026-09-27.

The repository includes a TELEMETRY.md file that documents what usage data the tool collects. Reviewing this file before deploying in shared or regulated environments is advisable.

The graft build command regenerates the graft/ directory in place. The README describes the graph as a regenerable cache comparable to node_modules. The README does not document a migration procedure for existing graph directories across format changes between major versions. Reviewing the CHANGELOG before upgrading in a production deployment is a reasonable precaution, particularly if teammates share the same wiring files from .claude/ and each generates their own local graph from them.

## Conclusion

Graft fits an engineering team that runs Claude Code or Cursor on a large, multi-developer codebase and notices a measurable exploration cost on every agent session. Setup takes two npm commands, and the wiring shared between teammates is a small commit. Teams with codebases that fit comfortably in a model context window, or with no regular AI agent usage, will not recoup the build-time cost. Before deploying, read TELEMETRY.md and run graft init --dry-run to verify the files it writes against your team's data handling requirements.

## FAQ

### How does Graft keep the context graph current as code changes?

Every query triggers a structural rebuild against the working tree first. The README describes this as taking approximately three milliseconds when nothing has moved, so the graph reflects uncommitted edits as well as committed changes. The graft check command gives a freshness signal without calling a model.

### Does Graft send code to external servers?

The structural build uses tree-sitter and runs entirely locally with no external calls. The deep build, which generates plain-English summaries, sends code to the language model provider you configure through GRAFT_PROVIDER and GRAFT_API_KEY. The graph output itself is written only to the local graft/ directory; Graft does not maintain its own backend.

### What exactly gets committed when a team adopts Graft?

The graft/ directory is added to .gitignore and is not committed. What goes into version control is the wiring graft init places in .claude/ and AGENTS.md. Teammates clone that wiring and then run graft build locally to generate their own copy of the graph.

## Sources

- [Issues](https://github.com/trailhq/Graft/issues)
- [License: MIT](https://github.com/trailhq/Graft/blob/main/LICENSE)
- [Project website](https://graft.nanonets.ai)
- [README](https://github.com/trailhq/Graft/blob/main/README.md)
- [trailhq/Graft on GitHub](https://github.com/trailhq/Graft)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/trailhq-graft