Graft codebase map wey coding agent fit query

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 rediscover structure

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

The cause dey 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, with full cost. For large repository, orientation phase fit 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 half, na why skill wey hold agent to the smallest change wey work dey worth pairing with map instead of choosing between dem.

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

You already dey use weaker version of this. AGENTS.md wey state your conventions dey stop agent from deriving your conventions again every time. Generated map dey stop am from deriving your structure again. The difference na who write am. You dey write the instruction file by hand, so e stay small. Parser dey 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.

Wetin Graft dey actually build

Two artefacts, both dey 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 source, the exact source files with content hash, typed wikilinks to other nodes (depends_on, part_of, uses, implements), and notes section wey remain after regeneration. You fit use am record context wey parser no fit infer.

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

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

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

Install Graft and pin the version

Graft dey need Node.js 20 or newer, and e get MIT license. As of August 2026, current release na 0.10.1, while the first published version, 0.1.0, get date for July 2026. Treat am as young software.

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

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

Then connect am to repository wey you own:

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

graft init go ask which of your coding agents e suppose connect, then e go build the graph. Run --dry-run first and read the list of files wey e plan to touch, because some of dem dey outside the repository. graft init dey idempotent and e no overwrite existing configs, so e safe to run am again.

As of August 2026, the wiring cover Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf and AdaL. Claude Code get the deepest integration: MCP server entry, statusline wey show graph size and staleness, post-edit hooks wey rebuild the graph, and skill file under .claude/. The others get instruction or rule file wey tell the agent say the tools dey available. So, "Supported" mean say Graft write the wiring. If agent skip its own rules file, e go skip the map too. Na the usual reason agents dey ignore the instructions wey you write for dem, and the same thing apply here.

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

After graft init, expect these:

• 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 fit 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 and .adal/skills/graft/SKILL.md: marker-fenced sections wey dem append to any files wey match the agents you pick.
• ~/.codex/config.toml, ~/.codex/hooks.json and ~/.codex/hooks/graft/graft-hooks.cjs: machine-wide files, wey dem write only when you select Codex. graft init --no-global no include dem, and graft init --no-hooks no include the hook shim by itself.

The graph na cache, like node_modules. No commit am. E dey regenerate from the code within seconds, e dey change for almost every edit, and committing am go turn one-line fix to several-hundred-file diff 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 enter 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 something else 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.10.1", "mcp"]
    }
  }
}

Retrieval tools wey your agent dey call instead of grep

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

Every one get CLI twin, and na through am 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 this: agent receive pointer and open one file, instead of reading ten files to find the correct one. graft viz dey open interactive viewer for localhost if you wan inspect the graph by yourself. If graft ask return nothing useful for question wey you fit answer within thirty seconds, the graph don stale or your language dey for broad tier, and the map no go help your agent too.

One cost dey easy to miss. Six tool definitions dey injected into system prompt for every request throughout the whole session. You go pay that 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 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. Query dey parse again only files wey dem stat change, and project document am as roughly 3 ms overhead. Rebuild for end of turn dey touch only files where code move. Set GRAFT_NO_REFRESH=1 or pass --no-refresh to answer from graph wey dey disk without parsing again. Pass --no-reuse to force cold re-parse of everything. Na this one you want after you upgrade Graft itself.

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

Make staleness dey visible:

graft check .
echo $?

Exit status 0 mean say graph match code. Exit status 1 mean drift. Run am from pre-push hook, or for the branch inside CI, so map wey don old for six months no fit confidently answer question about code wey dem rewrite for March.

Read the published benchmark numbers carefully

Graft headline claim na “up to 4x cheaper and 3x faster, with better or no loss of correctness”. Na the project own benchmarks publish for its README dey support these numbers. Here be the two runs wey e report complete.

[
  {
    "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 dey among dem, with three trials for each task. E report 42% fewer 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 reproduce five merged PocketBase pull requests at cost of 11.02 US dollars, compared with 13.91 for the baseline.

Treat everything as vendor benchmark. Two things limit wetin the results fit tell you. The controlled sweep include Graft own repository, wey be the codebase wey its authors tune against. SWE-bench Verified na public dataset of issues from well-known open-source Python projects, and tools dey usually optimise for public datasets, whether anybody plan am or not. Neither result dey describe 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 against 93% without am. The increase to 66% from 54% only appear 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 go 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.

Where codebase map no dey help again?

• Repository already fit inside 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 mean graft callers fit miss caller, or produce one because two names collide. Confirm with graft grep before you trust blast radius.
• Graph don stale and nobody notice. graft check dey exit 1 when drift happen, but that one only useful if something dey run am. Use hook or CI step, no be personal habit.
• Monorepo need scoping. Single-git monorepo dey auto-split with workspace file, go.mod, pyproject.toml or Cargo.toml, and graft ask "..." --in services/billing/ dey narrow query to one sub-project. The same way wey make you use 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

I commit the graft/ folder go git?

No. graft build dey add graft/ go your .gitignore automatically, because the graph na regenerable cache like node_modules. E dey change for almost every edit, so if you commit am, real diffs go hide under hundreds of generated files. Commit the wiring wey 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 dey untrack am.

Graft cost money to run?

The structural half no 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 half: 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 token on the graph itself.

How much codebase map fit save for my repository?

Nobody fit tell you without measuring. The project report 42% fewer tokens for its own 162-run sweep and 23% for SWE-bench Verified, both compared with baseline wey no get map. Both na vendor benchmarks; one of dem run partly on Graft own repository, and neither 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 happen to the graph when I refactor?

Structure dey parse itself again. Graft dey inspect the working tree and re-parse only files wey change, so e go pick up rename for the next query with roughly 3 ms overhead. E dey see uncommitted work because e dey read files, no be git history. The model-written summaries na the part wey go stale: every node store content hash of its sources, and when source change, e mark the node stale instead of rewriting am. Run graft check . to see the drift, then graft build --deep to refresh the written half.

Which coding agents fit use Graft today?

As of August 2026, graft init dey wire Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf and AdaL. 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 skip. The others receive rules or steering file. Any other MCP client fit use the server directly by registering command npx -y @nanonets/graft@0.10.1 mcp.