Fun AI Lab

AI coding agents like Claude Code, Cursor, and Gemini possess impressive code generation capabilities. However, when pointed at a repository containing 100,000 lines of code across 500 files, these agents encounter significant operational hurdles.

They spend dozens of context-window turns executing primitive file searches, running recursive grep commands, and attempting to map call chains manually. This process consumes thousands of tokens, slows down response times, and increases LLM API costs.

Graft solves this specific issue. Developed as an open-source context layer for large codebases, Graft parses your repository into a deterministic structural graph. Instead of forcing an AI model to blindly guess where code dependencies lie, Graft provides precise subgraphs directly to the agent. The result is faster, cheaper, and more accurate AI-assisted development.

---

Why Code Context Breaks Traditional AI Agents

When an AI agent receives a prompt like “Fix the user authentication error in the payment webhook handler,” it cannot immediately pinpoint the exact file requiring changes.

Without structural knowledge of the codebase, the agent defaults to a trial-and-error discovery loop:
1. It lists top-level directories.
2. It searches for keywords like payment or webhook.
3. It opens candidates individually to inspect imports and class definitions.
4. It reads downstream database queries and middleware configurations.

Without Graft:
Prompt -> Agent -> list_dir -> grep -> read_file_1 -> read_file_2 -> read_file_3 -> Context Overload -> Code Fix

This discovery routine suffers from major structural limitations:

• Massive Token Inflation: Every file read pushes thousands of lines of irrelevant boilerplate code into the agent’s context window.
• Context Degradation: As the context fills with raw text search results, the LLM loses track of early instructions—leading to hallucinated method signatures or ignored edge cases.
• High Financial Cost: Repeated API round-trips for basic file discovery rack up substantial costs, especially on premium frontier models.
• Speed Delays: Waiting for 10 sequential tool calls to complete turns a quick 5-second bug fix into a two-minute waiting period.

Traditional Vector Retrieval-Augmented Generation (RAG) fails to resolve this problem effectively for source code. Vector embeddings measure text similarity, not functional code relationships. Knowing that two functions share similar documentation strings does not tell an AI agent whether Function A actually calls Function B, or if modifying Class C will break Module D.

---

What Graft Is and How It Works

Graft bridges the gap between raw text matching and semantic structural awareness. It acts as an ambient code graph layer that operates locally or within continuous integration (CI) environments.

Instead of relying on fuzzy vector embeddings, Graft builds a explicit code graph by performing static analysis on your source files using Abstract Syntax Trees (ASTs).

graph TD
    A[Developer Prompt / Feature Request] --> B[AI Agent e.g., Claude Code, Cursor]
    B -->|MCP Query: Find blast radius & dependencies| C[Graft Graph Engine]
    C -->|Parse ASTs & Call Graphs| D[Local Graph Index Node/Edge Store]
    D -->|Return Exact Subgraph Context| C
    C -->|Structured Code Topology| B
    B -->|Precise Tool Call & Code Modification| E[Correct Code Patch]

    style C fill:#0066cc,stroke:#333,stroke-width:2px,color:#fff
    style D fill:#f8f9fa,stroke:#0066cc,stroke-width:2px,color:#1a1a1a

When you point Graft at a codebase, it indexes the code structure:
* Nodes: Symbol declarations (functions, classes, interfaces, types, methods, exported variables).
* Edges: Structural relationships (CALLS, IMPORTS, EXTENDS, IMPLEMENTS, TYPE_REFERENCES).

When your AI agent needs to locate code or analyze impact, it queries Graft’s Graph Server via the Model Context Protocol (MCP) or CLI utilities. Graft returns only the essential nodes, definitions, and dependent signatures—stripping away thousands of lines of unneeded implementation boilerplate.

---

Performance Benchmarks: The Proof in the Numbers

Adding a dedicated graph layer directly improves performance across all core metrics. Benchmarked against cold instances of Claude Code, Graft yields substantial savings in time, cost, and accuracy.

Benchmark Metric	Standard Cold Claude Code	Claude Code + Graft Integration	Net Improvement
Tool-Call Reduction	Baseline (100%)	54% of baseline	-46% fewer tool calls
Token Consumption	Baseline (100%)	58% of baseline	42% token savings (4× cheaper)
Task Execution Time	Baseline (100%)	40% of baseline	60% faster (3× throughput)
SWE-bench Accuracy	54.0% correct	66.0% correct	+12.0 percentage points

By reducing unnecessary discovery steps, Graft keeps the prompt history clean. This allows the underlying model to dedicate its focus to logic, edge cases, and synthesis—resulting in higher task completion success on complex benchmarks like SWE-bench Verified.

---

Core Capabilities and Built-in Toolkit

Graft is more than a passive background server; it ships with developer-focused CLI utilities designed for both human engineers and automated agents.

1. High-Speed Symbol Search (graft grep)

Standard grep returns lines of matching text without contextual awareness. graft grep queries the AST graph index directly.

# Search specifically for symbol definitions matching 'processOrder'
graft grep --type symbol processOrder

# Find all callers of 'validateJWT' across the entire repository
graft grep --referencing validateJWT

Instead of scanning thousands of physical files line-by-line, Graft fetches exact symbol hits instantly from its memory-mapped graph cache.

2. Architectural Summarization (graft map)

When an agent starts a task in an unfamiliar folder, reading every file to understand the architecture consumes context rapidly. graft map generates a concise high-level outline of interfaces, class hierarchy, and exported entry points.

# Output a clean topological map of a module
graft map src/services/billing

The AI agent receives a structured summary containing class names, public signatures, and relationships without loading single implementation details or internal logic blocks.

3. Interactive Codebase Visualization (graft viz)

Understanding complex microservices or tightly-coupled monorepos can be difficult. Running graft viz spins up a local web application that renders interactive dependency graphs.

graft viz --port 3000

Developers can visually trace upstream callers, downstream dependencies, and circular imports directly in the browser—making architectural reviews much simpler.

---

Real-World Use Cases

Monorepo Refactoring at Scale

Refactoring shared utility libraries in large monorepos often causes unintended downstream breaks.

By utilizing Graft’s graph query capabilities via MCP, an agent can check every dependent function across TypeScript, Python, and Go modules before changing a function signature. It updates call sites in a single pass without needing manual file searches.

Automated Pull Request “Blast Radius” Analysis

By integrating the official Graft GitHub App into your CI/CD pipeline, every incoming pull request gets an automated assessment evaluating its potential blast radius.

PR #142: Modify AuthToken payload format
--------------------------------------------------
Graft Impact Analysis:
- Direct AST changes: 1 file (src/auth/token.ts)
- Downstream Call Graph Impact: 14 callers across 4 services
- High-Risk Dependency: Payment Processing Service (line 88)

This automated check alerts reviewers to unintended ripple effects before code reaches production environments.

Instant Developer Onboarding

When joining a project with hundreds of thousands of lines of code, engineers can query Graft directly via local AI CLI tools to answer specific structural questions:

“Which services write to the PostgreSQL orders table, and what middleware checks their permissions?”

Graft traces the data model and outputs a precise workflow diagram in seconds.

---

Common Misconceptions and Pitfalls

Myth 1: “Vector RAG with Embeddings is Sufficient for Codebase Context”

Reality: Vector search works well for finding textual similarities in documentation, but it lacks structural understanding. Vector embeddings cannot guarantee precise function call chains, inheritance paths, or interface implementations. Graft’s AST-based graph provides deterministic structural facts rather than approximate semantic guesses.

Myth 2: “Graft Replaces AI Coding Extensions”

Reality: Graft does not replace tools like Claude Code, Cursor, or Gemini. It serves as an underlying context engine. Think of Cursor or Claude Code as the driver, and Graft as an active, high-resolution map navigation system.

Pitfall: Forgetting to Keep the Local Graph Updated

While Graft handles fast incremental re-indexing on file edits, running massive branch switches or manual Git checkouts outside your editor can occasionally leave the graph stale. Running a quick graft init or enabling file-system watch daemons keeps your context index synchronized.

---

Step-by-Step Guide: Getting Started with Graft

Setting up Graft on your local workspace takes less than two minutes.

Step 1: Install the CLI Tooling

Graft is distributed as a global Node package. Ensure Node.js (v18+) is installed, then run:

npm install -g @nanonets/graft

Step 2: Initialize Your Repository

Navigate to your repository’s root directory and build the initial graph index:

cd /path/to/your/project
graft init

Graft automatically scans your project, identifies supported programming languages (TypeScript, JavaScript, Python, Go, Rust, Java, C++), parses the file trees via Tree-sitter, and generates a local index inside .graft/.

Step 3: Connect to Claude Code or MCP-enabled Agents

To wire Graft into Claude Code or any MCP-compatible environment (such as Cursor or VS Code extensions), configure your MCP configuration file (mcp.json):

{
  "mcpServers": {
    "graft": {
      "command": "graft",
      "args": ["mcp"]
    }
  }
}

Once configured, your AI coding agent automatically gains access to Graft’s graph analysis tools (grep, map, symbol_lookup, impact_analysis) during prompt execution.

---

Technical Architecture Overview

To understand why Graft operates efficiently without eating CPU cycles, it helps to examine its architecture:

┌─────────────────────────────────────────────────────────────┐
│                      Graft CLI / MCP                        │
├─────────────────────────────────────────────────────────────┤
│   graft grep    │    graft map    │        graft viz        │
├─────────────────┴─────────────────┴─────────────────────────┤
│                   Tree-sitter Parser Engine                 │
│       (AST Generation for TS, JS, PY, Go, Rust, C++)        │
├─────────────────────────────────────────────────────────────┤
│                   Graph Builder & Indexer                   │
│   (Nodes: Symbols, Types | Edges: Calls, Imports, Extends)  │
├─────────────────────────────────────────────────────────────┤
│                In-Memory Node/Edge Store                    │
└─────────────────────────────────────────────────────────────┘

1. Tree-sitter AST Extraction: Instead of using slow regex matching, Graft leverages native Tree-sitter bindings to create precise Abstract Syntax Trees across multiple programming languages.
2. Deterministic Symbol Mapping: It builds symbol definitions, tracking scope boundaries, export visibility, and exact type annotations.
3. Graph Assembly: Relationships are linked in a fast local graph engine.
4. MCP Interface: Agents query the graph via natural JSON-RPC tools over standard I/O, receiving structured outputs that fit neatly into token limits.

---

Actionable Tips to Maximize Efficiency

To get the best performance out of Graft and your AI coding agents, follow these best practices:

• Combine Graft with Target System Prompts: Instruct your agent in its .cursorrules or system prompt to use Graft tools first before resorting to full file scans.
  Always run 'graft grep' or query the Graft MCP server to inspect symbol definitions and caller chains before reading entire source files.
• Use Monorepo Path Filter Flags: On massive repositories, constrain graft map queries to your current working directory to keep token payloads ultra-lean.
• Commit .graftignore Files: Exclude large build artifacts, compiled distributions, or vendor directories (node_modules/, dist/, vendor/) to keep index builds instantaneous.

---

Final Thoughts: The Future of AI Development

AI coding agents are evolving rapidly, but their effectiveness depends heavily on the quality of context provided. Pointing a high-powered model at an unstructured pile of source files leads to wasted context and unnecessary API expenditure.

Graft shifts AI-assisted development from trial-and-error discovery to precise, graph-guided execution. Delivering structural codebase context directly to your agent results in 60% faster resolution times, 42% token savings, and noticeably higher solution accuracy.

If you are using Claude Code, Cursor, or Gemini on non-trivial codebases, integrating Graft into your workflow is one of the quickest ways to upgrade your AI toolchain.

📂 Explore the open-source repository on GitHub: https://github.com/trailhq/Graft