SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor

Graft codebase map wey coding agent fit query

Graft go parse your repo with tree-sitter, build linked markdown and symbol maps, then expose am over MCP so your coding agent no rediscover structure every session.

Coding agents dey use codebase map na wetin

Codebase map for coding agents na persistent index of your repository wey agent fit look things up inside, instead of make e grep from scratch every new session. Graft na one implementation of this idea. E parse your code with tree-sitter, write one folder of linked markdown nodes plus per-symbol wiring graph, then serve retrieval tools over MCP (model context protocol, the standard interface wey coding agents dey use call outside tools).

Graft no be proxy and e no be gateway. Nothing dey between your agent and the model API. The map na folder for disk wey agent dey read. This difference decide the problem wey you dey solve: self-hosted token gateway dey meter and route the requests wey you already dey send, while map dey change how many requests you need send at all.

This technique older pass this tool, and e go outlive am. Learn the technique first, then learn the mechanics.

Why coding agents dey burn context to discover structure again

Watch agent as e start work for repository wey e don see fifty times before. E dey list directories. E dey grep for symbol. E dey open three files to find which one define the function, then fourth one to find who dey call am. None of this na the task. Na orientation, and na input tokens pay for am every session.

The cause simple. Model no get memory between sessions. Everything wey agent learn about your layout dey inside context window wey dem discard when session end. So the same discovery go run again from zero, and you go pay for am again. Prompt caching only reduce cost for identical prompt prefix wey e see within the last five minutes, or the last hour with extra cost, so e no fit carry yesterday exploration enter today session. For large repository, orientation phase cost pass the edit: ten tool calls to locate the code, one to change am. Orientation na only one half of that bill and edit na the other, na why skill wey make agent stick to the smallest change wey work worth pairing with map instead of choosing between dem.

Map break that loop by moving discovery from model go disk. Parser go walk through repository once, record which symbol dey defined where and which symbol dey call which, then keep that record current as code dey change. Agent ask one question and get answer with file and line attached. Repeated exploration become cheap lookup.

You already dey use weaker version of this. AGENTS.md wey state your conventions stop agent from deriving your conventions again every time. Generated map stop am from deriving your structure again. Difference na who write am. You hand-write the instruction file, so e remain small. Parser generate the map, so e fit cover ten thousand files. For where the budget actually dey go inside session, how Claude Code dey spend its context window cover the accounting.

Graft dey build wetin actually

Two artefacts dey, both inside one graft/ folder for repository root.

The first one na node graph wey dem write as linked markdown, one file for each node. Each node get plain-English summary, a "crux" of the important logic lines wey dem lift from the source, the exact source files with content hash, typed wikilinks to other nodes (depends_on, part_of, uses, implements), and notes section wey survive regeneration, so you fit record context wey parser no fit infer.

The second one na graft/.graph/wiring.json, the per-symbol structural graph wey tree-sitter extract: definitions, references, and call edges between dem.

This separation matter because na only one half need model. graft build na pure tree-sitter, and e no ever call LLM (large language model), so e dey deterministic and e cost nothing. graft build --deep add the written summaries and per-symbol cruxes, and na model calls you dey pay for those ones.

Language support dey come in tiers, and the tier tell you how much you fit trust a call graph. TypeScript, JavaScript, Python, Go, Java, Kotlin, PHP, Swift, and R get scope-aware cross-file resolution. Rust, C, C++, C#, Ruby, Scala, Elixir, Solidity, OCaml, Zig, Dart, Clojure, Nix, and Lua get symbols plus generic call edges. This mean say edge fit be name match instead of resolved reference. Compiler-grade edges dey opt-in with --lsp and language server like rust-analyzer or gopls.

Graft install then pin the version

Graft need Node.js 20 or newer, and e get MIT license. As of 17 October 2026, the current release na 0.23.0, wey dem publish on 15 October 2026. The first published version na 0.1.0, dated July 2026. Treat am as young software. Release 0.22.0, wey dem publish on 14 October 2026, rename the project to Trail-code: the same code now also ship as @trailhq/trail-code with a trail command, while @nanonets/graft still keep the graft command.

This guide pin 0.21.1, wey dem publish on 29 September 2026 and na the last release before the rename, because 0.22 and 0.23 change commands wey this guide depend on. From 0.22 onward, graft check compare your branch diff with the repo team learnings and exit 1 when e find conflict. Drift detection move to graft build --check, and the MCP tools names na trail_*. The server still answer the old graft_* names. The 0.23.0 changelog also talk say for repo wey dem set up with trail, the map move to .trail/cache/ and Claude Code no longer get MCP server, while the README still describe graft/ and .mcp.json. Read the changelog and run --dry-run before you move the pin.

npm install -g @nanonets/graft@0.21.1
npm ls -g @nanonets/graft

npm ls -g suppose print @nanonets/graft@0.21.1. Pin that version on purpose. Bare npm install -g @nanonets/graft go resolve the latest tag when you run am. For project wey dey release several minor versions every month, this fit give you one tool on Tuesday and give your colleague another one wey e install on Monday. Pinned version keep the CLI flags and graph format the same for everybody, so you upgrade only when you decide.

Then connect am to repository wey belong to you:

cd /path/to/your/repo
graft init --dry-run
graft init

graft init ask which coding agents you want to connect, then e build the graph. Run --dry-run first and read the list of files wey e plan to change, because some of dem fit dey outside the repository. graft init dey idempotent and e no overwrite existing configs, so you fit run am again safely. To undo am, graft uninstall remove every file and config entry wey Graft write. E dey do dry run until you pass -y.

The same prompt get checkbox for telemetry. Since release 0.12.0, Graft dey send anonymous usage ping by default: bucketed counts and fixed labels, never your code, file paths, or repository name. Events dey post at most once every day. The one exception na the install event, wey npm postinstall hook hand to the background sender immediately. Untick the box during graft init, run graft telemetry disable, or set DO_NOT_TRACK=1 to turn am off. E also turn itself off for CI. graft telemetry debug print the batch wey e for send without actually sending am.

For 0.21.1, the wiring cover Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent, and Google Antigravity. Hermes Agent don be first-class graft init host since release 0.13.0. For the pinned version, graft init --agents hermes and graft init --agents antigravity select those two like any other host. Grok join for release 0.13.0, and you select am with graft init --agents grok. Claude Code get the deepest integration: an MCP server entry, a statusline wey show graph size and staleness, post-edit hooks wey rebuild the graph, and a skill file under .claude/. The others get instruction or rule file wey tell the agent say the tools dey available. Hermes Agent and Antigravity both read the AGENTS.md section. Grok also get MCP block inside its own config. So when we say “Supported”, e mean say Graft write the wiring. If an agent skip its own rules file, e go skip the map too. Na this be the normal reason agents no dey follow the instructions wey you write for dem, and the same thing apply here.

Wetin go land for your repository, and wetin no go enter git

After graft init, expect these ones:

  • graft/: the markdown node graph and graft/.graph/wiring.json. E don add am to .gitignore for you.
  • .mcp.json: e register the graft MCP server so Claude Code go start am.
  • .claude/settings.json: e merge am for the correct place, adding the statusline and the post-edit hooks.
  • AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursor/rules/graft.mdc, .kiro/steering/graft.md, .windsurf/rules/graft.md, .grok/skills/graft/SKILL.md and .adal/skills/graft/SKILL.md: marker-fenced sections wey append to any files wey match the agents you choose.
  • .grok/config.toml: a repo-level [mcp_servers.graft] block, wey e write only when you select Grok.
  • ~/.codex/config.toml, ~/.codex/hooks.json and ~/.codex/hooks/graft/graft-hooks.cjs: machine-wide files, wey e write only when you select Codex and ~/.codex/ don already exist. graft init --no-global skip dem, and graft init --no-hooks skip the hook shim by itself.

The graph na cache, like node_modules. No commit am. E dey regenerate from the code within seconds, e change for almost every edit, and if you commit am, one-line fix go turn into diff for several hundred files wey no reviewer go read. Commit the wiring instead, including AGENTS.md and .mcp.json. Teammate fit clone the repository, run graft build, and get their own local graph.

Check say the ignore rule land before your first commit:

grep -n graft .gitignore
git status --short

grep suppose print one line wey contain graft/, and git status --short suppose list nothing under graft/. If files under graft/ show for that output, e mean say the ignore entry dey missing or another place don override am. Fix am before you commit, because git go continue track file once you don add am, and later .gitignore edit no go untrack am.

If you prefer register the MCP server by hand, or pin am to the same version wey you install, the entry small:

{
  "mcpServers": {
    "graft": {
      "command": "npx",
      "args": ["-y", "@nanonets/graft@0.21.1", "mcp"]
    }
  }
}

The retrieval tools wey your agent dey call instead of grep

Graft dey expose six tools through MCP. graft_find_code dey return ranked nodes for task description, together with file and line. graft_file_api dey return every signature for one file without bodies. graft_trace_calls dey follow callers or callees several levels deep. graft_find_all dey return regex hits wey e group by symbol. graft_repo_map dey give you first look at repository wey you never know before. graft_check_freshness dey report whether graph still match the code.

All of dem get CLI twin, and na through that you fit check wetin your agent actually dey receive:

graft map .
graft ask "where do we validate the refresh token"
graft skeleton src/auth/session.ts
graft callers validateRefreshToken
graft callers validateRefreshToken --direction out
graft grep "refresh_token" --json

graft ask suppose print ranked nodes with file:line references instead of file contents. Na the whole mechanism be that: agent receive pointer and open one file, instead of reading ten files to find the correct one. graft viz go open interactive viewer for localhost if you wan inspect the graph by yourself. If graft ask no return anything useful for question wey you fit answer within thirty seconds, no just change the wording and ask again. Ranked retrieval fit miss, and the project own skill file talk say weak hits mean say you should switch to graft grep, graft skeleton or graft callers. If those ones still no give enough result, check for drift (graft check . on the pinned 0.21.1, graft build --check from 0.22 upward) and confirm which tier your language dey, because stale graph or broad-tier edges go fail your agent the same way.

One cost dey easy to miss. System prompt for every request during the whole session dey receive six tool definitions. You go pay that cost whether agent use the map or not. For repository wey small enough to fit inside context, this fixed charge fit pass the exploration wey e save.

Wetin dey happen to the graph when code change

Structural refresh cheap and automatic. Graft dey read your working tree instead of git, so edit wey you never commit and edit wey you don stage dey equally visible to am. Every query first dey check the working tree, then e dey re-parse only files wey change. The 0.21.1 docs put this check around 3 ms when nothing move; the current README talk say na few tens of milliseconds, about 50 ms for the project own repository. Turn-end rebuild dey touch only files where code move. Set GRAFT_NO_REFRESH=1 or pass --no-refresh to answer from graph wey dey disk without re-parsing. Pass --no-reuse to force cold re-parse of everything, na this one you need after you upgrade Graft itself.

The model-written part dey behave differently, and na there e dey quietly go wrong. Summaries and cruxes dey cached. Every node record content hash of its sources, so when source file change, the node dey mark as stale instead of showing am as current. That flag only help if something act on am. Refresh with graft build --deep, wey go spend model tokens again.

Make staleness visible:

graft check .
echo $?

For the pinned 0.21.1, exit status 0 mean say graph match the code, while exit status 1 mean drift. From 0.22, graft check go exit 1 when e detect conflict with team learning instead, and the drift gate na graft build --check, so change the command when you move the pin. Run am from pre-push hook, so map wey don old for six months no fit confidently answer question about code wey dem rewrite for March. The 0.21.1 README describe graft check as local freshness signal, and the current README list build --check for CI. Either way, graft/ dey git-ignored, so fresh CI checkout go start without graph unless the job build one.

Read the published benchmark numbers well

The 0.21.1 README start with "up to 4x cheaper and 3x faster, with better or no loss of correctness". The current README don remove that line and e start with smaller numbers: "Across 162 runs of the same agent on the same tasks: 32% lower cost, 42% fewer uncached input tokens, 60% less time, and the same share of correct answers." Na the project own benchmarks be these, and e publish dem for the README. Na the two runs wey e report in full be these.

ChartGraft's own published benchmark results, versus a no-map baseline, as of October 2026
Di data wey dey behind dis chart
[
  {
    "label": "Controlled sweep",
    "run_count": 162,
    "token_saving_pct": 42,
    "tool_call_saving_pct": 46,
    "correctness_pct": 93,
    "baseline_correctness_pct": 93
  },
  {
    "label": "SWE-bench Verified",
    "run_count": 50,
    "token_saving_pct": 23,
    "tool_call_saving_pct": 25,
    "correctness_pct": 66,
    "baseline_correctness_pct": 54
  }
]

The controlled sweep na 162 runs across two repositories, and Graft itself dey among dem, with three trials for each task. E report 42% fewer uncached input tokens and 46% fewer tool calls. The SWE-bench Verified run na 50 instances, with the same model for both arms, and e report smaller saving: 23% of tokens and 25% of tool calls. Another run of 15 PocketBase tasks, ten developer questions plus five reproduced merged pull requests, cost 11.02 US dollars altogether, compared with 13.91 for the baseline.

Treat everything as vendor benchmark. Two things limit wetin e fit tell you. The controlled sweep include Graft own repository, and na the codebase wey the authors tune against. SWE-bench Verified na public dataset of issues from popular open-source Python projects, and tools dey usually optimise for public datasets, whether anybody plan am or not. Neither one be statement about your private monorepo, wey get its own naming habits and dead code.

Correctness need another careful look. For the controlled sweep, e no change: 93% with the map, compared with 93% without am. The increase to 66% from 54% show only for SWE-bench Verified. Tool wey reduce your token bill while quality remain the same still be good trade. But no carry the SWE-bench correctness result over to the sweep token result and quote both as one claim.

Measure your own token delta before you believe any of it

The only number wey matter na the one from your repository. This method go take one afternoon.

Pick one task wey you fit repeat exactly. Question better pass edit, because edit go change the repository and the second run no longer be the same experiment. “Which module dey enforce the rate limit for the login route” na the correct shape.

Turn on telemetry and send am go your own terminal:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claude

The console exporter dey print metric records as dem dey collect. The one wey you want na claude_code.token.usage, wey carry one type attribute of input, output, cacheRead or cacheCreation. Orientation dey show for input and cacheRead, because na there file contents dey enter. Add the two together.

Run the task three times, each one for fresh session, with the map wired. Then remove the graft entry from .mcp.json and run am three more times. Compare medians instead of single runs, because agent runs fit vary plenty and one unlucky run fit tell you the opposite of the truth. Record the tool-call count too: tool calls na the mechanism, while tokens na the effect. So, if tokens reduce but tool calls no reduce, something else don move.

Then subtract the costs wey the benchmark no show. graft build --deep dey spend model tokens for every full refresh. The six tool schemas dey go along with every request. If your agents dey run for server wey you rent, putting a hard ceiling on agent spend go turn this from surprise to budget, and what a coding agent's telemetry actually reports go explain wetin leaves the machine after you enable the exporter.

Codebase map dey stop to help for where?

  • Repository already small enough to enter context. One small service no need map, and you still dey pay for six tool schemas for every request. If your agent dey find any file today with one or two tool calls, skip am.
  • Your language dey broad tier. Generic call edges fit make graft callers miss one caller, or create one because names collide. Confirm with graft grep before you trust the blast radius.
  • Graph don stale and nobody notice. For 0.21.1, graft check dey exit 1 when drift happen (from 0.22, graft build --check dey do am), but this only useful if something dey run am. Use pre-push hook, no be memory.
  • Monorepo need scoping. One single-git monorepo no split, but graft build dey detect sub-projects from pnpm-workspace.yaml, package.json workspaces or per-package go.mod, pyproject.toml or Cargo.toml, then use dem as ranking scopes, while graft ask "..." --in services/billing/ dey narrow query to one sub-project. The same thinking wey lead to nested AGENTS.md files for each package apply to the map.
  • Agent dey ignore the wiring. Watch the tool calls for real session before you conclude say agent dey use the map. If agent still dey run grep, e dey show say e never read the rules file.

FAQ

Make I commit the graft/ folder to git?

No. graft build dey add graft/ to your .gitignore automatically, because the graph na cache wey fit regenerate like node_modules. E dey change for almost every edit, so if you commit am, real diffs go dey hide under hundreds of generated files. Commit the wiring wey dey tell agents say the map dey exist, including AGENTS.md and .mcp.json, then make each teammate run graft build locally. Verify with grep -n graft .gitignore and git status --short before your first commit, because git go continue track file once you don add am, and editing .gitignore afterwards no go stop git from tracking am.

Graft dey cost money to run?

The structural part no dey cost money. graft build, graft ask, graft check and the six MCP retrieval tools na tree-sitter operations wey never call model. graft build --deep na the paid part: e dey write plain-English summaries and per-symbol cruxes through an LLM, configured with GRAFT_PROVIDER, GRAFT_API_KEY and GRAFT_MODEL, plus GRAFT_BASE_URL for any OpenAI-compatible endpoint. You fit run Graft with structure only and never spend any token on the graph itself.

How much codebase map fit save for my repository?

Nobody fit tell you without measuring. The project reports 42% fewer uncached input tokens for its own 162-run sweep and 23% fewer tokens for SWE-bench Verified, both compared with baseline wey no get map. Both na vendor benchmarks; one run partly on Graft own repository, and neither one describe your private code. Run one repeatable question three times with the map and three times without am, with CLAUDE_CODE_ENABLE_TELEMETRY=1 and OTEL_METRICS_EXPORTER=console set, then compare the median of claude_code.token.usage for the input and cacheRead types.

Wetin go happen to the graph when I refactor?

Structure go parse itself again. Graft dey check the working tree and parse again only the files wey change, so e go detect rename for the next query. When nothing move, that check dey cost roughly 3 ms for 0.21.1 and some tens of milliseconds for the current release, and e dey see uncommitted work because e dey read files instead of git history. The summaries wey model write na the ones wey go become stale: each node dey store content hash of its sources, and when source change, e mark the node stale instead of rewriting am. Check for drift (graft check . for 0.21.1, graft build --check from 0.22), then run graft build --deep to refresh the written half.

Which coding agents fit use Graft today?

For the pinned 0.21.1, graft init dey wire Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent and Google Antigravity, eleven hosts altogether. The changelog don list Hermes Agent as first-class host since 0.13.0, and hermes and antigravity na ordinary --agents ids for the pinned release. Claude Code get the most: MCP server entry for .mcp.json, statusline, post-edit hooks and skill file under .claude/. Codex get AGENTS.md section plus machine-wide entries under ~/.codex/, wey graft init --no-global no include. Grok get skill file plus MCP block for .grok/config.toml. Hermes Agent and Antigravity dey read AGENTS.md section, while the others receive rules or steering file. Any other MCP client fit use the server directly by registering the command npx -y @nanonets/graft@0.21.1 mcp.

Dis article help you?