Graft Review: Can an Agent Repo Map Be a Team Asset?

Graft solves a real problem, and the viral version of its pitch is wrong about the part engineering leaders care about most. The problem is genuine: a coding agent starts most tasks blind, greps its way through your repository, rebuilds a picture it already built yesterday, and bills you for the rediscovery. Graft writes that picture down as linked markdown nodes so the next task starts oriented.

The claim circulating in feeds is that the map then travels through git and the whole team inherits it. Graft's own documentation says the opposite. In the official Graft repository, the README states that "the graph is a local, regenerable cache (like node_modules), not something you commit". graft build adds graft/ to your .gitignore automatically, and each teammate runs graft build to generate their own copy.

That is not a flaw. It is the correct default, and it changes what you are actually rolling out: a shared convention and a cheap rebuild, not a shared document. Our verdict after reviewing the project on 18 August 2026: wire Graft into one repository and measure it, but plan the team story around what genuinely belongs in version control. This page owns the product-specific "Graft review" and "agent repo map in git" question. Our Graphify review owns the queryable codebase knowledge graph decision, and the graph engineering guide owns when a graph earns its cost at all.

What is Graft?

Graft is an MIT-licensed TypeScript CLI that turns a repository into a folder of linked markdown nodes plus a per-symbol code graph, then wires that output into the agents you already use. Installation is two commands, npm install -g @nanonets/graft and graft init. It builds in two tiers, and the difference between them decides both your cost and your privacy review.

Two design choices are worth naming, because they are what makes the tool interesting rather than the benchmark table. First, there is no vector store: the project's own description is files your agent reads, with no server, database or embeddings. Second, freshness is a loop rather than an index: every query stats the working tree against the last build's fingerprint and rebuilds only what moved, structurally and at zero token cost, so answers describe uncommitted edits too.

That second choice is the substantive engineering. A stale map is worse than no map, because the agent trusts it. Prior art matters here: Aider shipped a tree-sitter repository map ranked by PageRank in October 2023. The ranked repo map is not new. The refresh loop and the multi-agent wiring are the contribution.

Does Graft commit the repo map to git?

No, and you should not want it to. What travels through version control is the wiring: the files graft init drops into .claude/, the marker-fenced Graft section in AGENTS.md, and the MCP configuration. The generated graph under graft/ is gitignored and rebuilt per clone.

We reached the same conclusion the hard way on this site's own repository. We run coding agents in parallel git worktrees, and generated graph output is deliberately excluded from version control there, because the generated filenames collide across concurrent branches and a conflict in a machine-written file costs review time while producing no review value. A committed map also goes stale at the speed of whichever branch you are on, which is exactly when an agent is most likely to act on it.

So the honest framing of the team benefit is narrower than the viral one, and more useful. Graft does not give your teammate the knowledge your agent built. It gives your teammate a two-second command that rebuilds an equivalent map from the same source of truth: the code. That is a better guarantee than a shared file, because it cannot drift. It is also a rollout task, not a documentation task.

What should live in git, then?

The useful rule is short: commit what a human is accountable for, and regenerate what a parser can rederive. Generated structure is cheap and self-correcting. Intent is neither.

1. Decisions and constraints. Build and test commands, boundaries the agent must not cross, why the ugly module stays ugly, which interface is a contract. This is what AGENTS.md exists for, a format used by more than 60,000 open-source projects and now stewarded by the Agentic AI Foundation under the Linux Foundation. It is hand-written, reviewed in pull requests, and worth the maintenance.
2. Derived structure. Call graphs, symbol maps, ranked file lists. Rebuildable, so gitignore it and make the rebuild fast and automatic.
3. Institutional knowledge that is not code. Runbooks, domain rules, decisions with an owner and a review date. That belongs in a governed store, which is a different build with different rules. Our AI-ready company wiki architecture covers it.

Teams that get this wrong usually fail in one of two directions. They commit generated output and inherit merge noise plus confident stale answers. Or they write nothing down at all and expect the tool to infer intent that was never recorded anywhere. A repo map cannot tell an agent that a table is being migrated and must not gain columns. Only a human can. The same discipline shows up in our software handover checklist, which was written for the human version of the identical problem: what has to be written down before the person who knows it leaves.

How strong is the evidence behind Graft's numbers?

The mechanism is credible and every published number is vendor-run. That combination deserves a pilot, not a procurement decision. Graft publishes three separate measurement efforts, and they are not equally strong.

The SWE-bench arm is the strongest because grading is deterministic. It is also the one to read most carefully. Full SWE-bench Verified contains 500 human-validated instances; 50 is a tenth of it, and the write-up does not say which tenth. The two instances it discusses by name are Django, and one widely used 50-instance subset, SWE-bench-verified-mini, draws only from Django and Sphinx. Neither fact tells you what Graft actually sampled, and that gap is the limitation worth naming: without the instance list, the project and language coverage behind the number is unknown. Six extra instances on an undisclosed sample of 50, run once, is a directional signal. It is not a leaderboard position, and it is not evidence about your Kotlin service.

The most actionable finding is one the marketing does not lead with. The sweep ran a third variant: pull, where the agent gets Graft's tools but nothing is injected up front, so context is paid for only when asked. Pull gave up most of the speed gain and reached 98% correctness against 93% for a cold agent. If being right matters more than being fast, that is the configuration to test first, and it is the opposite of the "push the bundle up front" default that produces the headline latency figure.

What does Graft actually cost?

There is no licence fee. That is where the free part ends, and the real budget has four lines.

• Structural builds are genuinely free. Tree-sitter parsing, the refresh loop and the structural queries never call a model. For a large repository this is the majority of the value at zero marginal cost.
• The concept tier is a token line item. graft build --deep summarizes files and symbols under your key, cached by body hash, so the cost lands on churn. Budget it per active developer per clone, not once per repository.
• Maturity is a cost. The project was created on 3 July 2026 and its latest tag is v0.9.0, with roughly 3,500 stars and dozens of open issues at the time of writing. A pre-1.0 dependency sitting in your agent's context path deserves a pinned version and a tested upgrade path, the same as any other build tool.
• Reviewer time is the line people forget. Machine-written summaries are unreviewed prose about your architecture. When an agent acts on a wrong summary, a senior engineer pays for it in review. Our cost-per-action framework gives the right denominator: cost per accepted change, including review minutes and rework, not tokens saved per query.

Tokens are the easiest thing to measure and the least interesting thing to optimize. If you want the systematic version of that argument, our token budget playbook covers caching, routing and compression in the order that protects quality.

What do EU teams need to check before rolling this out?

The split between tiers maps neatly onto the compliance question, which is unusually convenient.

A plain graft build is local and deterministic, and the project states it ships no telemetry, with the only network calls being the model requests you configure yourself. For regulated work that is a strong position: you get orientation, symbol maps and call graphs without any code leaving the machine.

graft build --deep is a different decision. It sends file and symbol content to whichever provider you point it at, which makes that provider a processor for your source code. Settle the DPA, the region, the retention window and the training-use terms before the first deep build, not after someone runs it on the payments service. Our EU data residency guide covers the provider side, and redaction before prompting covers repositories where fixtures and logs carry personal data.

One more control worth setting early: the generated graph is a compact, readable description of how your system fits together. Treat it as source code. It should not end up in a support bundle, a public CI artifact or a screenshot in a ticket.

Graft, a repo map, or a knowledge graph: which problem are you solving?

Most teams reaching for a tool like this have one of five different problems, and only two of them are solved by a repo map.

If you are still deciding whether any of this pays for itself, start one level up. Our analysis of context as the real bottleneck explains why the category exists, and the context-compression field report shows what measured savings look like in our own delivery work rather than in a vendor table.

A two-week Graft pilot that produces a decision

1. Pick one repository that hurts. Large, multi-language, poorly documented, actively worked on. A clean 40-file service will not show a difference.
2. Freeze the task set before you install anything. Ten real orientation and localization questions plus five changes you have already merged, reset to their base commits.
3. Run three arms, not two. Cold, push (a bundle up front) and pull (tools available on demand). The vendor's own data says these behave differently on correctness.
4. Grade changes with tests, not file overlap. Touching the right files is a weak proxy. Your test suite is the grader you already trust.
5. Count cost per accepted change. Tokens, wall-clock, retries and reviewer minutes, divided by changes that survived review.
6. Attack freshness. Run queries on a dirty tree, mid-rebase, after a large rename and on a branch that deleted a subsystem. A map that lies confidently is the main risk in this category.
7. Decide the deep-build provider deliberately. Route it through your existing approved model path, or leave the concept tier off for the pilot and measure the free structural tier alone.
8. Check what lands in git. Review the wiring diff, confirm graft/ is ignored and confirm nothing generated slipped into a commit.
9. Pin the version. Then upgrade once during the pilot on purpose, and see what the upgrade costs.
10. Set the scale gate in advance. Adopt only if verified correctness or cost per accepted change improves enough to pay for the rebuild, the review and a pre-1.0 dependency.

Two weeks is enough because the measurement is mechanical, provided somebody owns it. Wavect's AI enablement service runs this comparison inside your repository and hands over the harness, so the result survives the consultant. The Twinsoft AI case study shows how we handle traceable AI output and reviewer control on production work. If you are weighing implementation against a strategy document, compare AI enablement with generic AI consulting first, then tell us which repository is the painful one.

Research boundary

Status checked 18 August 2026 against Graft's public repository and project site. This is an independent architecture and buyer review, not a sponsored post, a security audit or our own controlled benchmark of the tool. Every performance figure quoted here is published by the vendor and graded by the vendor's harness, with the SWE-bench arm using the official grader. The project is pre-1.0 and moving fast, so pin a version and re-read the current documentation before you standardize on it.