Claude Code Tool Calls Cut by 94%: The Local Code Knowledge Graph Powerhouse https://github.com/Jakedismo/codegraph-rust…

This is CodeGraph-Rust, the magic tool where an MCP server pre-indexes your entire codebase into a local knowledge graph! It single-handedly outperforms Claude Code, Cursor, and all other Agents: by building the graph in advance, subsequent queries traverse the graph directly instead of scanning files fully each time. This results in a 94% drop in tool calls, soaring speeds, massive token savings, and an instantly elevated experience! Once you use it, there’s no going back.

Jakedismo/codegraph-rust

Source: https://github.com/Jakedismo/codegraph-rust

CodeGraph

Your codebase, understood.

CodeGraph transforms your entire codebase into a semantically searchable knowledge graph that AI agents can actually reason about—not just grep through.

Ready to get started? Jump to the Installation Guide for step-by-step setup instructions.

Already set up? See the Usage Guide for tips on getting the most out of CodeGraph with your AI assistant.

The Problem

AI coding assistants are powerful, but they’re flying blind. They see files one at a time, grep for patterns, and burn tokens trying to understand your architecture. Every conversation starts from zero.

What if your AI assistant already knew your codebase?

What CodeGraph Does Differently

1. Graph + Embeddings = True Understanding

Most semantic search tools create embeddings and call it a day. CodeGraph builds a real knowledge graph:

Your Code → Build Context → AST + FastML → LSP Resolution → Enrichment → Graph + Embeddings
↓         ↓           ↓            ↓              ↓             ↓            ↓
Packages  Nodes/edges Type-aware   API surface    Graph        Semantic
          Fast        linking      Features       Dataflow/Docs Features
          patterns                 (hybrid)       (hybrid)

When you search, you don’t just get “similar code”—you get code with its relationships intact. The function that matches your query, plus what calls it, what it depends on, and where it fits in the architecture.

Indexing enrichment adds:

• Module nodes and module-level import/containment edges for cross-file navigation
• Rust-local dataflow edges (defines, uses, flows_to, returns, mutates) for impact analysis
• Document/spec nodes linked to backticked symbols in README.md, docs/**/*.md, and schema/**/*.surql
• Architecture signals (package cycles + optional boundary violations)

Indexing tiers (speed vs richness)

Indexing is tiered so you can choose between speed/storage and graph richness. The default is fast.

Tier behavior details:

• fast: disables build context, LSP, enrichment, module linking, dataflow, docs/contracts, and architecture; filters out Uses/References edges.
• balanced: enables build context, LSP symbols, enrichment, module linking, and docs/contracts; filters out References edges.
• full: enables all analyzers and LSP definitions; no edge filtering.

Configure the tier:

• CLI: codegraph index --index-tier balanced
• Env: CODEGRAPH_INDEX_TIER=balanced
• Config: [indexing] tier = "balanced"

Indexing prerequisites (LSP-enabled tiers)

When the tier enables LSP (balanced/full), indexing fails fast if required external tools are missing.

Required tools by language:

• Rust: rust-analyzer
• TypeScript/JavaScript: node and typescript-language-server
• Python: node and pyright-langserver
• Go: gopls
• Java: jdtls
• C/C++: clangd

If indexing appears to stall during LSP resolution, you can adjust the per-request timeout:

• CODEGRAPH_LSP_REQUEST_TIMEOUT_SECS (default 600, minimum 5)

If LSP resolution fails immediately and the error includes something like Unknown binary 'rust-analyzer' in official toolchain ..., your rust-analyzer is a rustup shim without an installed binary. Install a runnable rust-analyzer (e.g., via brew install rust-analyzer or by switching to a toolchain that provides it).

Optional architecture boundary rules

If you want CodeGraph to flag forbidden package dependencies, add codegraph.boundaries.toml at the project root:

[[deny]]
from = "your_crate"
to = "forbidden_crate"
reason = "explain the boundary"

Indexing will emit violates_boundary edges when a depends_on relationship matches a deny rule.

2. Agentic Tools, Not Just Search

CodeGraph doesn’t return a list of files and wish you luck. It ships 4 consolidated agentic tools that do the thinking:

Each tool accepts an optional focus parameter for precision when needed:

Each tool runs a reasoning agent that plans, searches, analyzes graph relationships, and synthesizes an answer. Not a search result—an answer.

View Agent Context Gathering Flow - Interactive diagram showing how agents use graph tools to gather context.

Agent Architectures

CodeGraph implements agents using Rig the default and recommended choice (legacy react and lats implemented with autoagents still work). Selectable at runtime via CODEGRAPH_AGENT_ARCHITECTURE=rig:

Why Rig is Default: The Rig-based backend delivers the best performance with modern thinking and reasoning models. It is a native Rust implementation that supports internal sub-architectures and provides features like True Token Streaming and Automatic Recovery.

Internal Rig Sub-Architectures: When using the rig backend, the system automatically maps the consolidated agentic tools to the most effective reasoning strategy:

• LATS (Tree Search): Deep multi-path exploration for complex, non-linear tasks.
  • Automatically used for: agentic_architecture (structure), agentic_quality, and agentic_context (question).
• ReAct (Linear): High-speed, focused reasoning for direct data lookups.
  • Automatically used for: agentic_context (search/builder), agentic_impact, and agentic_architecture (api_surface).
• Reflexion (Auto-Recovery): A self-correcting fallback that kicks in automatically if the primary strategy fails to find an answer. It analyzes the failure and retries with a refined plan.

Agent Bootstrap Context

Agents can start with lightweight project context so their first tool calls are not blind. Enable via env:

• CODEGRAPH_ARCH_BOOTSTRAP=true — includes a brief directory/structure bootstrap + contents of README.md and CLAUDE.md+AGENTS.md or GEMINI.md (if present) in the agent’s initial context.
• CODEGRAPH_ARCH_PRIMER="" — optional custom primer injected into startup instructions (e.g., areas to focus on).

Why? Faster, more relevant early steps, fewer wasted graph/semantic queries, and better architecture answers on large repos.

Notes:

• Bootstrap is small (top directories summary), not a replacement for graph queries.
• Uses the same project selection as indexing (CODEGRAPH_PROJECT_ID or current working directory).

# Use Rig for best performance with thinking and reasoning models (recommended)
CODEGRAPH_AGENT_ARCHITECTURE=rig ./codegraph start stdio

# Use default ReAct for traditional instruction models
./codegraph start stdio

# Use LATS for complex analysis
CODEGRAPH_AGENT_ARCHITECTURE=lats ./codegraph start stdio

All architectures use the same 4 consolidated agentic tools (backed by 6 internal graph analysis tools) and tier-aware prompting—only the reasoning strategy differs.

3. Tier-Aware Intelligence

Here’s something clever: CodeGraph automatically adjusts its behavior based on the LLM’s context window that you configured for the codegraph agent.

• Running a small local model? Get focused, efficient queries.
• Using GPT-5.1 or Claude with 200K context? Get comprehensive, exploratory analysis.
• Using grok-4-1-fast-reasoning with 2M context? Get detailed analysis with intelligent result management.

The Agent only uses the amount of steps that it requires to produce the answer, so tool execution times vary based on the query and amount of data indexed in the database. During development, the agent used 3-6 steps on average to produce answers for test scenarios.

The Agent is stateless; it only has conversational memory for the span of tool execution. It does not accumulate context/memory over multiple chained tool calls; this is already handled by your client of choice, which accumulates that context, so CodeGraph just needs to provide answers.

Hard cap: Maximum 8 steps regardless of tier (10 with env override). This prevents runaway costs and context overflow while still allowing thorough analysis.

Same tool, automatically optimized for your setup.

4. Context Overflow Protection

CodeGraph includes multi-layer protection against context overflow—preventing expensive failures when tool results exceed your model’s limits.

Per-Tool Result Truncation:

• Each tool result is limited based on your configured context window.
• Large results (e.g., dependency trees with 1000+ nodes) are intelligently truncated.
• Truncated results include _truncated: true metadata so the agent knows data was cut.
• Array results keep the most relevant items that fit within limits.

Context Accumulation Guard:

• Monitors total accumulated context across multi-step reasoning.
• Fails fast with clear error message if accumulated tool results exceed safe threshold.
• Threshold: 80% of context window × 4 (conservative estimate for token overhead).

Configure via environment:

# CRITICAL: Set this to match your agent's LLM context window
CODEGRAPH_CONTEXT_WINDOW=128000 # Default: 128K

# Per-tool result limit derived automatically: context_window × 2 bytes
# Accumulation limit derived automatically: context_window × 4 × 0.8 bytes

Why this matters: Without these guards, a single agentic_impact query on a large codebase could return 6M+ tokens—far exceeding most models’ limits and causing expensive failures.

5. Hybrid Search That Actually Works

We don’t pick sides in the “embeddings vs keywords” debate. CodeGraph combines:

• 70% vector similarity (semantic understanding)
• 30% lexical search (exact matches matter)
• Graph traversal (relationships and context)
• Optional reranking (cross-encoder precision)

The result? You find handleUserAuth when you search for “login logic”—but also when you search for “handleUserAuth”.

Intelligence

Why This Matters for AI Coding

When you connect CodeGraph to Claude Code, Cursor, or any MCP-compatible agent:

Before: Your AI reads files one by one, grepping around, burning tokens on context-gathering.

After: Your AI calls agentic_impact({"query": "UserService"}) and instantly knows what breaks if you refactor it.

This isn’t incremental improvement. It’s the difference between an AI that searches your code and one that understands it.

Why this is powerful for code agents

CodeGraph shifts the cognitive load (search + relevance + dependency reasoning) into CodeGraph’s agentic tools, so your code agent can spend its context budget on making the change, not discovering what to change.

What an agentic tool returns (example)

agentic_impact returns structured output (file paths, line numbers, and bounded snippets/highlights) plus analysis:

{
  "analysis_type": "dependency_analysis",
  "query": "PromptSelector",
  "structured_output": {
    "analysis": "...what depends on PromptSelector and why...",
    "highlights": [
      {
        "file_path": "crates/codegraph-mcp-server/src/prompt_selector.rs",
        "line_number": 42,
        "snippet": "pub struct PromptSelector { ... }"
      }
    ],
    "next_steps": ["..."]
  },
  "steps_taken": "5",
  "tool_use_count": 5
}

What a code agent would otherwise have to do

Without CodeGraph’s agentic tools, a code agent typically needs multiple “single-purpose” calls to reach the same confidence:

• Search for the symbol (often multiple strategies: text + semantic + ripgrep-style search)
• Open and read multiple files (definition + usages + callers + related modules)
• Reconstruct dependency/call graphs mentally from partial evidence
• Repeat when a guess is wrong (more reads, more tokens)

This burns context quickly: reading “just” a handful of medium-sized files + surrounding context can easily consume tens of thousands of tokens, and larger repos can push into hundreds of thousands depending on how much code gets pulled into context.

With CodeGraph, the agent gets pinpointed locations and relationships (plus bounded context) and can keep far more of the context window available for planning and implementing changes.

Quick Start

1. Install

# Clone and build with all features
git clone https://github.com/yourorg/codegraph-rust
cd codegraph-rust
./install-codegraph-full-features.sh

macOS faster builds (LLVM lld)

If you develop on macOS, you can opt into LLVM’s lld linker for faster linking:

# Install LLVM so ld64.lld is on PATH (Homebrew)
brew install llvm

# Use the repo-provided Makefile targets
make build-llvm
make test-llvm

2. Start SurrealDB

# Local persistent storage
surreal start --bind 0.0.0.0:3004 --user root --pass root file://$HOME/.codegraph/surreal.db

3. Apply Schema

cd schema && ./apply-schema.sh

4. Index Your Code

codegraph index /path/to/project -r -l rust,typescript,python

🔒 Security Note: Indexing automatically respects .gitignore and filters out common secrets patterns (.env, credentials.json, *.pem, API keys, etc.). Your secrets won’t be embedded or exposed to the agent.

5. Connect to Claude Code

Add to your MCP config:

{
  "mcpServers": {
    "codegraph": {
      "command": "/full/path/to/codegraph",
      "args": ["start", "stdio", "--watch"]
    }
  }
}

That’s it. Your AI now understands your codebase.

The Architecture

View Interactive Architecture Diagram - Explore the full workspace structure with clickable components and layer filtering.

┌─────────────────────────────────────────────────────────────────┐
│ Claude Code / MCP Client                                        │
└─────────────────────────────────┬───────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│ CodeGraph MCP Server                                            │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Agentic Tools Layer                                       │  │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌──────────────┐  │  │
│  │  │ Rig     │  │ ReAct   │  │ LATS    │  │ Tool Execution│  │  │
│  │  │ Agent   │  │ Agent   │  │ Agent   │  │ Pipeline      │  │  │
│  │  └────┬────┘  └────┬────┘  └────┬────┘  └──────┬───────┘  │  │
│  │       └────────────┼────────────┼──────────────┼──────────┘  │
│  │                    └────────────┼──────────────┼──────────┘  │
│  └─────────────────────────────────┼──────────────┼─────────────┘
│                                    │              │
│  ┌─────────────────────────────────┼──────────────┼─────────────┐