How to Install NanoNets Graft for Codex and Claude Code

The safest way to install NanoNets Graft is to preview its changes before allowing it to wire itself into Codex or Claude Code. Graft can build a structural map of a repository without an API key, then expose that map through instructions, command-line searches and MCP tools.

The short version is:

npm install -g @nanonets/graft@0.10.1
cd path/to/your/repository
graft init --agents agents claude --no-global --dry-run
graft init --agents agents claude --no-global

The agents ID is the Codex-style integration. claude selects Claude Code. The first command inside the repository writes nothing; it lists the files Graft intends to touch. The second keeps Codex’s initial setup out of your user profile, although the selected Claude integration still adds project-level Claude hooks, a status line, a skill and an MCP entry.

What is NanoNets Graft?

Graft is an MIT-licensed code-context tool for AI coding agents. It parses a repository into a local graph that records files, symbols, calls and dependencies. Codex, Claude Code and other supported agents can query that graph before opening source files one by one.

This guide covers the NanoNets project published as @nanonets/graft. Several unrelated developer tools also use the name Graft, so check the npm scope and repository owner before installing anything.

This is not another coding model. It sits between your repository and the agent you already use. The practical idea is simple: build the map once, keep its structural layer current, and let the agent ask targeted questions such as “what calls this function?” or “which files handle authentication?”

If you want a manual visual context graph rather than an automatic repository parser, ThoughtDAG lets you branch, merge and export selected reasoning for a coding agent.

The basic structural graph uses tree-sitter and does not need a model or API key. An optional --deep build sends code-derived material to a model provider to create richer summaries and concept nodes. That privacy difference matters, so this guide starts with the structural build.

The project publishes its own token, speed and correctness benchmarks. They are useful evidence about what the developers tested, but they remain vendor-produced results. I would judge Graft on your own repository by comparing the quality of a few bounded read-only tasks before and after installation.

What Graft changes

graft init is not merely an index command. Depending on the selected agents and flags, it can update repository files and user-level Codex configuration. This is why the dry run belongs before the install.

Graft’s current Claude Code integration does not add a block to CLAUDE.md. It owns a separate skill file and merges settings into .claude/settings.json. For shared files such as AGENTS.md, the current source uses a fenced Graft section so unrelated instructions can remain in place.

Graft prerequisites for Windows, macOS and Linux

• Node.js 20 or newer: the current package manifest sets node >=20. A current LTS release is the least surprising choice.
• npm and npx: both normally arrive with Node.js.
• A source-code repository: start with a disposable clone or a clean Git worktree rather than a production checkout with uncommitted changes.
• Codex or Claude Code: install and authenticate the coding agent separately. Graft does not supply a model subscription.
• Git: Graft can parse files without Git, but Git gives you a clear diff and a reliable rollback checkpoint.

The npm installation command is the same in PowerShell, Windows Terminal, macOS Terminal and a normal Linux shell. Graft’s current changelog says Windows is part of its gating CI and documents several Windows fixes in the 0.9 release line. That is stronger evidence than assuming a Unix-focused Node tool happens to work on Windows, but it is not a promise that every repository or shell combination is bug-free.

Step 1: check Node.js, npm and Git

Open PowerShell or Terminal and run:

node --version
npm --version
npx --version
git --version

If Node is missing or older than version 20, install a supported release from the official Node.js download page, reopen the terminal and check again.

Do not reach for an administrator shell or sudo npm install -g as the first fix for a permissions error. The lower-risk alternatives are the npx route shown below or a user-owned Node installation managed by tools such as nvm, Volta or fnm.

Step 2: prepare a reversible test repository

Move into the repository you want Graft to map:

cd path/to/your/repository
git status --short

If git status already shows changes, stop and decide how those changes will be protected. A clean disposable clone is ideal. A separate branch is also useful when the repository is clean:

git switch -c try-graft

The goal is not to make Git part of Graft’s runtime. It is to make every configuration change visible and reversible.

Step 3: inspect the package and use a dry run

You can preview Graft without installing a permanent global command. This example pins the package version reviewed for this article:

npx @nanonets/graft@0.10.1 --version
npx @nanonets/graft@0.10.1 init --agents agents claude --no-global --dry-run

Read the complete output. Confirm that the target repository is correct and that every listed path makes sense. The explicit agent IDs avoid relying on auto-detection:

• agents means Codex-style hosts that read AGENTS.md.
• claude enables Graft’s Claude Code skill, settings, hooks and project MCP entry.
• --no-global prevents the Codex integration from changing ~/.codex/.
• --dry-run prints the plan and exits without writing.

If you only use one agent, select only that ID:

# Codex, repository-only first pass
npx @nanonets/graft@0.10.1 init --agents agents --no-global --dry-run

# Claude Code only
npx @nanonets/graft@0.10.1 init --agents claude --dry-run

Step 4: install the Graft command

The official README recommends a global npm install:

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

graft --version prints the installed version. If you would rather avoid a global command, keep using npx @nanonets/graft in place of graft.

The explicit version prevents npm from silently resolving a newer release while you follow version-specific file and rollback guidance. Check the project’s changelog before deliberately moving beyond the version reviewed here.

Step 5: apply the repository-only Codex and Claude Code setup

Run the same selection without --dry-run:

graft init --agents agents claude --no-global

This builds the structural graph if it is missing, adds the repository wiring for both agents, and leaves Codex’s user-level configuration alone. When it finishes, inspect the result:

git status --short
git diff
graft check
graft map

The generated graft/ directory is a local cache and should be ignored by Git. The wiring and instruction files may appear in the diff because those are the pieces a team can choose to share. Review them before committing anything.

Restart Claude Code after adding the MCP entry so it can load the new server. For Codex, this conservative mode supplies the AGENTS.md instructions but deliberately skips machine-wide MCP and hooks.

Step 6: test the graph before giving an agent a coding task

Use a read-only question whose answer you already understand:

graft ask "Where is authentication configured, and which files depend on it?" --source

Other useful checks are:

graft map
graft skeleton path/to/file.ts
graft callers functionName --depth 2
graft grep "error message" --fixed

Compare the returned files and symbols with the repository. A graph can make navigation cheaper; it cannot decide whether the code is correct. Keep the coding agent’s normal approval and sandbox controls enabled.

If you are evaluating coding-agent workflows more broadly, the site’s Aider guide covers a Git-centred alternative, while the GitHub Copilot SDK multi-agent tutorial shows how to build the agent layer rather than add repository context to an existing one.

Step 7: optionally enable the full Codex integration

Only do this after the repository-only setup behaves as expected. Preview the user-level changes first:

graft init --agents agents --dry-run

The current documentation says the full Codex route can register the MCP server in ~/.codex/config.toml, place a helper under ~/.codex/hooks/graft/, and add a post-edit entry to ~/.codex/hooks.json. Those settings can affect Codex in other repositories on the same account.

If the preview is acceptable, take a copy or diff of those files, then run:

graft init --agents agents

Restart Codex so it reloads its configuration. If you do not need automatic post-edit refreshes, use --no-hooks. If you only want repository instructions and intend to call the CLI yourself, keep --no-global.

These opt-out flags apply cleanly to the Codex-style route shown here. Selecting claude still installs Graft’s project-level Claude hooks, status line, skill and .mcp.json entry in version 0.10.1.

Step 8: optionally build the richer LLM layer

The structural commands are the privacy-friendly starting point. graft build --deep is different: it uses your chosen model provider to create file summaries, concept nodes and per-symbol explanations.

For an OpenAI-compatible service, set these values through your operating system’s environment-variable method:

GRAFT_PROVIDER=openai
GRAFT_API_KEY=your-provider-key
GRAFT_MODEL=your-provider-model
GRAFT_BASE_URL=https://your-provider.example/v1

Then run:

graft build --deep

Graft also supports the Anthropic wire format. An OpenAI-compatible local endpoint can be used through GRAFT_BASE_URL; the official example includes Ollama at http://localhost:11434/v1. The site’s LocalAI Windows and Docker guide is another route to a compatible local endpoint.

Do not assume “bring your own key” means private. A hosted deep build necessarily sends source-derived input to the provider you configure. Check the provider’s data handling, retention, regional and organisational policies before using private code.

Graft privacy and safety boundaries

• The structural graph is local: the official documentation says build, check, ask, grep, map and traversal use deterministic parsing without a model or API key.
• The deep layer is not automatically local: it sends requests to the model endpoint you configure. A local compatible endpoint is possible, but it is not the default merely because Graft runs on your computer.
• The cache can still be sensitive: graft/ may contain symbols, file paths, summaries and code excerpts. Git-ignore rules stop ordinary commits; they do not encrypt the directory or exclude it from every backup and sync product.
• Codex hooks can be machine-wide: use --no-global until you intentionally want those user-profile changes.
• Graft is not a sandbox: it improves the context supplied to a coding agent. It does not reduce that agent’s filesystem or command permissions.
• No telemetry is not the same as no network traffic: the project says it has no analytics or telemetry. npm and explicit version checks use the registry, while deep builds make the provider requests you configure.
• Back up Claude settings first: valid JSON configuration is merged, but the 0.10.1 implementation can treat an unparseable .claude/settings.json as empty and rewrite it. A dry run lists paths; it is not a content-level diff.

How to update Graft

For a global installation:

graft --version
npm view @nanonets/graft version
npm install -g @nanonets/graft@latest
graft --version

Read the changelog before upgrading, then rerun graft init --dry-run. A newer release can change Graft-owned helpers, managed sections and supported flags. Check git status and compare any user-level Codex configuration before applying the new wiring.

An npx invocation uses the package resolved by npm for that run. Pin a version when repeatability matters:

npx @nanonets/graft@0.10.1 --version

How to roll back or remove Graft

The official documentation reviewed for this article does not provide a single graft uninstall command. The cleanest rollback is therefore the Git checkpoint you made before init.

1. Close Codex and Claude Code so their hooks and MCP servers are not active.
2. Run git status --short and git diff.
3. Restore only the repository paths changed by the Graft setup. Do not use a broad clean or reset command if the repository contains unrelated work.
4. Remove the local graft/ cache after confirming that it is the generated directory for this repository.
5. If full Codex integration was enabled, restore the pre-install versions of ~/.codex/config.toml and ~/.codex/hooks.json, and remove only Graft’s helper under ~/.codex/hooks/graft/.
6. Remove the global package with npm uninstall -g @nanonets/graft.
7. Restart the coding agents and confirm that no Graft MCP tools or status hooks remain.

If the repository had a clean commit before installation, use its normal Git review and restore workflow. Manually deleting configuration keys is riskier than restoring a known-good version because the JSON and TOML files may contain settings belonging to other tools.

Common Graft installation problems

graft is not recognised or the command is not found

Close and reopen the terminal after the global npm install. If the command still is not on the path, use the non-global form:

npx @nanonets/graft --version

If that works, the package is available and the problem is the global npm binary path rather than Graft itself.

The install reports an unsupported Node version

Run node --version. The current package requires Node 20 or newer. Install a supported LTS release, reopen the terminal and retry.

graft init writes nothing in CI or a piped shell

Current Graft deliberately avoids guessing when there is no interactive terminal. Supply explicit agent IDs:

graft init --agents agents claude --no-global

Use --yes only when wiring every detected agent is genuinely intended.

The dry run lists files under ~/.codex/

Add --no-global. That keeps the first Codex setup at repository level:

graft init --agents agents --no-global --dry-run

Claude Code does not show the Graft MCP tools

Restart Claude Code after .mcp.json changes. If Graft reported that the file was invalid JSON, it leaves the file unchanged rather than overwriting it. Repair the JSON, rerun the dry run, then rerun init.

The graph is missing or stale

graft check
graft build
graft check

The current query commands refresh the structural graph when files change, but graft check remains the explicit drift report. LLM-generated deep summaries can remain stale until you intentionally run graft build --deep again.

Expected files do not appear in the graph

Read the language summary printed by graft build. The current project documents full-fidelity support for TypeScript/JavaScript, Python, Go and Java, plus broader parsing for several other languages. Unsupported extensions are skipped. Graft also respects Git ignore rules, so generated or deliberately ignored source may not be indexed.

The graph folder is called graft/, but an old example mentions .context

Follow the current CLI output and README. The current runtime source resolves the default to the visible graft/ directory. Some older comments and configuration examples still use the project’s previous .context name.

Graft FAQ

Is NanoNets Graft free?

The Graft source is available under the MIT licence. The structural graph does not need a paid model. The optional deep layer may incur charges from whichever model provider you configure.

Does Graft work on Windows?

The package requires Node.js rather than a separate Windows binary, and the current changelog says Windows CI is gating. Version 0.9 also contains specific Windows path, worktree and upgrade fixes. Use a current version and report the exact Graft, Node and Windows versions when troubleshooting.

Do I need an API key?

No for the structural build and search commands. Yes for graft build --deep, unless the compatible endpoint you operate uses no key.

Can I use Graft with both Codex and Claude Code?

Yes. Use the explicit IDs agents and claude. Start with:

graft init --agents agents claude --no-global --dry-run

Should I commit the graft/ directory?

Not with the current default setup. The current build treats graft/ as a regenerable local cache and adds it to .gitignore. Review and selectively commit the repository wiring files if the team wants to share the integration; teammates can run graft build to create their own graph.

Does Graft replace MCP?

No. Graft can expose its graph through an MCP server, but MCP is the connection layer rather than the graph itself. If you want to understand the broader local-model tool pattern, see the site’s llama.cpp MCP setup guide.

Will Graft make every coding task cheaper?

No result is guaranteed. The project reports improvements in its own controlled and SWE-bench tests, but repository size, language support, task shape, agent behaviour and graph freshness all matter. Test it on several questions where you can verify the answer, then compare total tool calls, time, cost and correctness for your own workload.

Is Graft worth installing?

Graft is most interesting for repositories large enough that an agent repeatedly wastes time rediscovering the same architecture. It is less compelling for a tiny project where opening the relevant files is already cheap.

My recommended trial is deliberately conservative: a clean test branch, the structural graph, explicit agents and claude IDs, --no-global, and one read-only question you can check yourself. Add the full Codex hooks or the provider-backed deep layer only when the basic graph has earned that extra access.

Primary sources

• NanoNets Graft official repository and README
• Official package manifest: version, Node requirement and dependencies
• Official Graft changelog
• Official provider and environment-variable example
• Official Claude Code integration targets
• Official supported-host registry and instruction targets
• Official graph-directory and ignore-file behaviour
• Official security policy