Graft Code Context Layer
Build a searchable code graph for coding agents so they spend less time and context rediscovering a repository.
The README separates local tree parsing from user-configured LLM calls, states that telemetry is absent, and enumerates repository and user-level writes. Initialization offers a picker, writes nothing without a TTY, and supports --dry-run, --no-global, --no-hooks, and --no-mcp, so confirmation is handled thoroughly. CI uses read-only permissions, disables credential persistence, and pins Actions by commit. Deductions apply because installation invokes an unseen postinstall script and runtime dependencies use floating compatible ranges; API keys may be passed on the command line, while storage, log redaction, exact source payloads, and provider-retention implications are not documented. No explicit uninstall or restoration procedure is supplied. Attribution is weak because the license names only “Context Graph Engine contributors,” while package repository, homepage, and issue metadata point to context-graph-engine rather than NanoNets/Graft.
The README, CI, and focused tests for retrieval, corrupt-index fallback, cross-platform behavior, and visible diagnostic notes largely support a coherent product. Tests show graceful fallback for missing or invalid sidecars and loud messages when structural lookup cannot answer. Deductions reflect internal documentation tension: graft/ is described both as an ignored local cache and as content to commit and synchronize through Git; the claim that both graph-building passes use a model is also awkward beside the later keyless structural-build description. Node 20, optional LSP dependencies, and provider configuration are documented, but complete handling of dependency-installation, provider, and network failures is not evidenced.
The sources define audiences and scenarios across single repositories, monorepos, multi-repository folders, CI, and several coding agents. Supported languages, structural versus deep layers, optional LSP behavior, skipped unsupported files, network boundaries, and disabling flags establish strong capability boundaries. Interactive selection, no-TTY safeguards, explicit agent flags, and query-coverage gates demonstrate precise activation. The environment-fit deduction is for evidence limited to Ubuntu and Windows on Node 20, without shown macOS, shell, local-model compatibility, or equally deep integration testing for every named agent.
The README has strong navigation and substantial quick-start, architecture, CLI, integration, language, and development material. Installation modes, touched paths, flags, and examples are detailed, and the complete MIT text agrees with package metadata. Pre-1.0 status, latest-release-only security support, unsupported-language skipping, and best-effort LSP behavior disclose meaningful limitations. Deductions apply because package metadata retains obsolete project URLs, weakening naming and update-path stability; the supplied material lacks a dedicated FAQ, comprehensive known-issues list, CHANGELOG, release/tag policy, and migration guidance. A security contact and response targets establish a maintenance channel, but ownership remains generic and publisher identity is not confirmed by the evidence.
Outputs are designed for direct use as Markdown nodes, file-line pointers, inline source, JSON, API skeletons, call traces, and explicit fallback notices. Tests concretely cover ranking, scope fusion, index parity, corruption fallback, and source retrieval, supporting high output usability. The context layer plausibly adds material value over repeated cold exploration. Deductions apply because the headline 4× cost, 3× speed, and SWE-bench correctness gains are self-reported in the README; no benchmark harness, raw records, or per-instance artifacts are included, so marginal value and cost-benefit are method-described but not fully substantiated by the supplied files.
Many operational claims trace to command documentation, configuration boundaries, CI, and targeted tests, with separate security and license files providing additional corroboration. Repository tests strongly support retrieval and fallback behavior. Deductions apply because benchmark performance and correctness figures appear only in the README and cannot be cross-checked against the supplied tests or artifacts; some measured results are phrased as broad conclusions, and the README conflicts over committing the cache and aspects of the build path. The document does explicitly distinguish the planned Markdown crux feature from what ships, which helps separate roadmap from current fact, but factual, inferred, and promotional claims are not consistently partitioned.
- Installation runs a postinstall script whose source is not supplied; inspect that script and the actual npm package contents before adoption.
- Deep builds send code content to the user-selected LLM provider; the evidence does not specify exact request payloads, key-log handling, or provider retention policies.
- Selecting Codex integration may modify ~/.codex/config.toml, the hooks directory, and user-level hooks.json for every repository; use --dry-run first and --no-global where appropriate.
- No explicit uninstall or rollback command is documented; back up affected configuration and retain dry-run output before initialization.
- The README conflicts on whether graft/ should be ignored or committed; teams should establish a generated-artifact policy before risking source-derived content in version control.
- Performance and SWE-bench claims lack auditable raw results or benchmark implementation in the supplied evidence and should not be treated as firm capacity, budget, or quality guarantees.
- The package repository, homepage, and issue URLs do not match the current NanoNets/Graft name; verify release provenance and the correct support channel manually.
What does this agent do, and when should you use it?
Graft is an open-source repository context layer for coding agents including Claude Code, Cursor, Codex, and Gemini. It uses tree-sitter locally to build a symbol-level code graph, per-file cards, and call relationships, while an optional LLM-powered deep build adds concept nodes, summaries, and crux excerpts. Its output lives under the local graft/ directory and is exposed through a CLI, an MCP server, and native instruction files for supported agents. Commands such as graft ask, grep, skeleton, callers, and map locate implementations, summarize API surfaces, trace dependencies, and orient an agent within a repository; graft viz provides a local interactive viewer. Structural builds and queries require no model, key, or network, while deep enrichment uses a user-selected OpenAI-compatible endpoint, Anthropic's native API, or another documented provider path. It is a fit for teams that want persistent, refreshable repository knowledge for coding agents while keeping the structural graph on the local filesystem.
When graft build runs, Graft reads source files in supported languages, extracts functions, classes, methods, imports, and call edges with tree-sitter, and writes graft/.graph/wiring.json plus file cards that mirror the source tree. graft build --deep asks the configured model to summarize files, groups those summaries into linked concept nodes, and adds per-symbol summaries and crux excerpts; results are cached by content or body hash. graft ask returns ranked nodes with exact file:line locations, graft skeleton lists signatures from one file, graft callers walks incoming or outgoing dependencies, graft grep groups regex matches by enclosing symbol, and graft map reports directory clusters, hubs, and hotspots. Before most queries, it compares the working tree with the last fingerprint and performs a model-free incremental structural refresh when files have changed. graft init can update AGENTS.md, GEMINI.md, Cursor rules, and other native agent files, register six MCP tools, and install Claude Code project skills, a status line, and synchronization hooks; selecting the agents host can also alter user-level Codex configuration. graft viz serves local Context, Code, and Outline views on localhost.
- A developer joining a large unfamiliar repository can run graft map and let a coding agent use graft ask to identify subsystems, entry points, and relevant files.
- A team making cross-file changes with Claude Code or Codex can use graft callers or graft_trace_calls to inspect callers and estimate a symbol's blast radius.
- An engineer trying to reduce prompt size can use graft skeleton or graft_file_api to provide signatures without sending complete function bodies.
- A team maintaining a monorepo or a directory of separate Git repositories can use automatic project discovery and narrow searches with --in.
- A maintainer performing an exhaustive migration can use graft grep or graft_find_all to collect every regex match, grouped by symbol and ranked by coupling.
- A team that cannot send structural code analysis to a hosted service can use the local tree-sitter build, search, and freshness checks, enabling LLM enrichment only when acceptable.
What are this agent's strengths and limitations?
- The base graph, call edges, builds, drift checks, and queries run deterministically with tree-sitter on the local machine, without a model key or network connection.
- It exposes the same repository context through a CLI, six MCP tools, agent instruction files, and a local visualization interface.
- It goes beyond a file index by extracting symbols and cross-file calls and imports, with dedicated callers, skeleton, grep, and map operations.
- Content-hash caching and query-time incremental refreshes account for staged, unstaged, and uncommitted source changes.
- Deep enrichment supports both OpenAI-compatible endpoints and Anthropic's native API, with the model, key, and endpoint controlled by the user.
- The project reports controlled measurements and SWE-bench Verified results covering correctness, tokens, calls, cost, and elapsed time.
- Model-written concept nodes, file summaries, and symbol cruxes require the adopter's own provider credentials and usage budget; automatic synchronization does not update this deep layer.
- Hand-written full-fidelity extraction is limited to TypeScript/JavaScript, Python, Go, and Java; other listed languages use the broader generic tier, and unlisted languages are skipped.
- Compiler-grade call edges require a matching language server on PATH and are documented as a best-effort optional enhancement.
- Initialization may touch several repository files and, for the agents host, machine-wide files under ~/.codex/, so adopters should use --dry-run and --no-global where appropriate.
- The graph is a local regenerable cache, so each teammate must run graft build rather than relying on a hosted shared index.
- The reported efficiency and correctness gains come from specific models, repositories, tasks, and harness settings and do not establish the same gains for every codebase.
How do you install or deploy this agent?
Node.js and npm or npx are required. Install the CLI globally and initialize the current repository with:
npm install -g @nanonets/graft
graft initTo avoid a global installation, run:
npx @nanonets/graft initIn CI or another non-TTY environment, init writes nothing unless the selection is explicit; use a command such as graft init --agents claude or graft init --yes. Preview every prospective write with graft init --dry-run, and add --no-global if ~/.codex/ must remain untouched. The basic graft build needs no API key. For graft build --deep, configure GRAFT_PROVIDER, GRAFT_API_KEY, and GRAFT_MODEL; with the OpenAI wire format, GRAFT_BASE_URL can target OpenAI, OpenRouter, Fireworks, Groq, LiteLLM, or a local compatible endpoint.
How do you use this agent?
For a minimal workflow, run graft build at the repository root, then use graft map for orientation or graft ask "task description" to find relevant code. Run graft skeleton <file> to inspect an API surface, graft callers <symbol> -d N to analyze transitive impact, and graft grep "<regex>" for exhaustive pattern search. After configuring provider credentials, use graft build --deep when concept nodes and model-written symbol context are wanted. Run graft check to detect drift and graft viz to open the localhost viewer. Agents can consume Graft through files and MCP configuration installed by graft init, or the server can be registered manually with npx -y @nanonets/graft mcp. Queries refresh changed structural data by default; --no-refresh or GRAFT_NO_REFRESH=1 disables that behavior.
How does this agent compare with similar options?
Compared with a cold Claude Code session that repeatedly greps, opens files, and follows imports from scratch, Graft builds and reuses a repository graph. In the documented 162-run controlled sweep, the pushed-context Graft arm averaged 46% fewer tool calls, 42% fewer tokens, and 60% lower latency while both arms scored 93% correctness; the pull-tool variant was slower but reached 98% correctness. On 50 SWE-bench Verified instances, Claude Code with Graft resolved 33 cases versus 27 for cold Claude Code while using fewer tokens, calls, and wall-clock time. These are project-reported results for the stated test configurations, not a guarantee for every repository.