codegraph-nav

Graph-intelligent, token-efficient code navigation for AI assistants

Surgical reading, execution flows, blast radius, risk scoring — 97% fewer tokens

What is codegraph-nav?

codegraph-nav is an MCP server that helps AI assistants explore codebases efficiently. Beyond basic search and read, it adds graph intelligence: blast radius analysis, execution flow tracing, risk-scored diffs, and community detection.

┌─────────────────────────────────────────────────────────────┐
│                    WITHOUT CODEGRAPH-NAV                    │
├─────────────────────────────────────────────────────────────┤
│  User: "Fix the payment bug"                                │
│                                                             │
│  Claude reads:                                              │
│  • payments.py      (500 lines)  → 7,500 tokens             │
│  • billing.py       (300 lines)  → 4,500 tokens             │
│  • models/order.py  (200 lines)  → 3,000 tokens             │
│  ─────────────────────────────────────────────              │
│  Total:                            15,000 tokens            │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                     WITH CODEGRAPH-NAV                      │
├─────────────────────────────────────────────────────────────┤
│  User: "Fix the payment bug"                                │
│                                                             │
│  1. codegraph_get_minimal_context → 100 tokens              │
│  2. codegraph_search("payment")  → 100 tokens              │
│  3. codegraph_read(payments.py, 45, 89) → 400 tokens        │
│  4. codegraph_blast_radius → 100 tokens                     │
│  ─────────────────────────────────────────────              │
│  Total:                               700 tokens            │
│                                                             │
│  SAVINGS: 95% fewer tokens + impact analysis!               │
└─────────────────────────────────────────────────────────────┘

Quick Start

1. Install

pip install codegraph-nav[mcp]    # MCP server + core
pip install codegraph-nav[all]    # Everything (tree-sitter, networkx, ast-grep)

2. Configure Claude Code (CLI)

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "codegraph-nav": {
      "command": "codegraph-nav-mcp"
    }
  }
}

3. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "codegraph-nav": {
      "command": "codegraph-nav-mcp"
    }
  }
}

4. Use It

In Claude, just ask to explore your codebase:

"Scan this project and find the payment function"
"What's the blast radius if I change auth.py?"
"Show me the architecture of this codebase"

Claude will automatically use codegraph-nav's 20 tools to explore efficiently.

Available Tools

Core Navigation

Graph Intelligence

Architecture & Domain

How It Works

flowchart TB
    subgraph SCAN["Step 1: Scan"]
        A[(Codebase)] --> B[codegraph_scan]
        B --> C[.codegraph.json]
    end

    subgraph NAVIGATE["Step 2: Navigate"]
        D[codegraph_search] --> E[file:line locations]
        E --> F[codegraph_read]
        F --> G[Only needed code]
    end

    subgraph GRAPH["Step 3: Analyze"]
        C --> H[codegraph_graph_build]
        H --> I[.codegraph.db]
        I --> J[blast_radius / flows / risk]
    end

    C --> D

1. Scan once - Creates .codegraph.json with all symbols indexed
2. Search & read surgically - Find symbols and load only the lines you need
3. Graph analysis - Build .codegraph.db for blast radius, flows, and risk scoring

Example Session

1. codegraph_get_minimal_context(path="/project", task="fix auth bug")
   → project: 142 files · 1847 symbols · py,js
   → hubs: config.py(8←), models.py(5←)
   → suggest: codegraph_search → codegraph_read → codegraph_get_dependencies

2. codegraph_search(query="authenticate")
   → src/auth.py:L10-30 [fn] authenticate

3. codegraph_read(file_path="src/auth.py", start_line=10, end_line=30)
   → Only those 20 lines (~200 tokens)

4. codegraph_blast_radius(path="/project", changed_files=["src/auth.py"])
   → blast(auth.py): 12 nodes · 5 files impacted

5. codegraph_detect_changes(path="/project")
   → risk: 0.78 HIGH | 3 files · 8 symbols changed

Detail Levels

All tools accept a detail_level parameter:

• minimal (default) - Compact, token-efficient output
• standard - Adds signatures, language breakdown, bidirectional counts
• verbose - Adds docstrings, dependency chains, per-file details

Workflow Prompts

5 built-in prompts that enforce token discipline:

Each prompt starts with codegraph_get_minimal_context and defaults to detail_level="minimal".

Supported Languages

*Install tree-sitter support: pip install codegraph-nav[ast] All tree-sitter analyzers fall back to regex when tree-sitter is not installed.

†Java/C/C++/PHP keep ast-grep as an intermediate fallback: with the [fast] extra installed but no tree-sitter grammar, they get a real AST parse (symbols + parents) before degrading to regex.

Every tree-sitter language extracts symbols with parent context, cross-file call dependencies (deps), and import specifiers resolved to internal repo files — which the graph builder turns into CALLS and IMPORTS_FROM edges. All except JS/TS also capture leading doc comments. Each symbol records which engine produced it ("source": "ast" | "ast-grep" | "regex"), and codegraph_stats shows the per-engine breakdown.

AST grammars ship through tree-sitter-language-pack (installed by the [ast] extra): one dependency with 160+ pre-compiled grammars for Linux/macOS/Windows — no C compiler needed. Installations that predate the pack keep working: the grammar registry also resolves the old individual tree-sitter-<lang> wheels. [dart] remains as a deprecated alias of [ast]. Without any grammar installed, every language falls back to the regex analyzer. Flutter needs no separate grammar; widgets are ordinary Dart classes.

Micro-Metadata Format

The scan output uses a compact ASCII tree with inline metadata:

my-project/
├── src/
│   ├── api/
│   │   ├── client.py [C:APIClient M:get,post] (5←)
│   │   └── routes.py [F:handle,validate] (3←)
│   └── core/
│       └── config.py [C:Config M:load] (Hub:8←)
└── tests/
    └── test_api.py [F:test_client]

═══ Summary ═══
28 files · 142 symbols · 12 hubs

Each file shows: classes (C:), functions (F:), methods (M:), and importer count (N←).

CLI Usage

# Generate code map
codegraph-nav scan /path/to/project
cgn scan .                              # Short alias

# Search for symbols
cgn search "process_payment"
cgn search -t class -o table

# Read specific lines
cgn read src/payments.py 45-89
cgn read src/payments.py 45-89 -c 3     # With context

# Get codebase stats
cgn stats

# Incremental update (only changed files)
cgn scan --incremental .

# Build the graph DB (.codegraph.db) from the code map
cgn graph build .                       # incremental (skip unchanged files)
cgn graph build . --full                # full rebuild
cgn graph stats .                       # node/edge counts (add -o json)

# Watch for changes; also rebuild the graph after each update
cgn watch . --graph

# Export as markdown
cgn export -f markdown -o docs/codebase.md

The graph build also computes a symbol-level PageRank (with the [graph] extra: pip install codegraph-nav[graph]), surfaced via the codegraph_get_hubs (scope="symbol") and codegraph_get_context MCP tools.

Python API

from codegraph_nav import CodeNavigator, CodeSearcher, LineReader

# Scan
navigator = CodeNavigator("/path/to/project")
code_map = navigator.scan()

# Search
searcher = CodeSearcher(".codegraph.json")
results = searcher.search_symbol("payment", symbol_type="function")

# Read surgically
reader = LineReader(root_path="/path/to/project")
content = reader.read_lines("src/pay.py", 45, 89)

Graph API

from codegraph_nav.graph import GraphStore, GraphBuilder, get_blast_radius, trace_flows

# Build graph from code map
store = GraphStore(".codegraph.db")
builder = GraphBuilder(store)
stats = builder.build_from_code_map(code_map)

# Blast radius
impact = get_blast_radius(store, changed_files=["src/auth.py"])
print(f"{impact['impacted_nodes']} nodes, {len(impact['impacted_files'])} files affected")

# Execution flows
flows = trace_flows(store)
for f in flows[:5]:
    print(f"{f['name']} crit:{f['criticality']:.2f} depth:{f['depth']}")

store.close()

Domain Intelligence API

from codegraph_nav.domain import detect_routes, detect_schemas, infer_project_tags

# Detect routes (FastAPI, Express, Django, Gin, etc.)
routes = detect_routes(code_map, root_path="/path/to/project")

# Detect ORM schemas (SQLAlchemy, Django, Prisma, etc.)
schemas = detect_schemas(code_map, root_path="/path/to/project")

# Infer domain tags (auth, db, cache, api, etc.)
tags = infer_project_tags(code_map)

Optional Dependencies

Performance

Tested on real-world open source projects:

Token savings:

• Small projects (50-100 files): 85-90% reduction
• Medium projects (100-500 files): 92-96% reduction
• Large projects (500+ files): 97-99% reduction

Development

git clone https://github.com/efrenbl/codegraph-nav.git
cd codegraph-nav
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python3 -m pytest tests/ -v

Requirements

• Python 3.10+
• MCP SDK 1.0+ (for MCP server only)

License

MIT License - see LICENSE for details.

Stop burning tokens reading entire files.
Scan once, search instantly, read surgically, analyze impact.