🧭 Code Navigator

An MCP server for token-efficient code navigation

Reduce token usage by 97% when exploring large codebases with Claude

Code Navigator is a Model Context Protocol (MCP) server that helps AI assistants like Claude explore codebases efficiently. Instead of reading entire files, it provides:

• Instant symbol search - Find functions, classes, methods by name
• Surgical reads - Load only the exact lines you need
• Dependency awareness - See what calls what without reading everything

┌─────────────────────────────────────────────────────────────┐
│                    WITHOUT CODE NAVIGATOR                   │
├─────────────────────────────────────────────────────────────┤
│  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 CODE NAVIGATOR                     │
├─────────────────────────────────────────────────────────────┤
│  User: "Fix the payment bug"                                │
│                                                             │
│  1. codenav_search("payment") → payments.py:45-89           │
│     Cost: ~100 tokens                                       │
│                                                             │
│  2. codenav_read(payments.py, 45, 89)                       │
│     Cost: ~400 tokens                                       │
│  ─────────────────────────────────────────────              │
│  Total:                               500 tokens            │
│                                                             │
│  SAVINGS: 97% fewer tokens!                                 │
└─────────────────────────────────────────────────────────────┘

pip install "codenav @ git+https://github.com/efrenbl/code-navigator.git"

Codenav is not published on PyPI — install it directly from the git repository. The import package and CLI commands are codenav / cnv. Add extras with pip install "codenav[mcp] @ git+https://github.com/efrenbl/code-navigator.git".

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

{
  "mcpServers": {
    "codenav": {
      "command": "codenav-mcp"
    }
  }
}

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "codenav": {
      "command": "codenav-mcp"
    }
  }
}

Add to your VS Code settings.json:

{
  "claude.mcpServers": {
    "codenav": {
      "command": "codenav-mcp"
    }
  }
}

# Check the entry point is available
codenav-mcp --help

# Test with MCP Inspector (optional)
npx @anthropic/mcp-inspector codenav-mcp

In Claude, just ask to explore your codebase:

"Scan this project and find the payment function"
"Show me the architecture of this codebase"
"What files import the UserService class?"

Claude will automatically use the Code Navigator tools to explore efficiently.

flowchart TB
    subgraph SCAN["Step 1: Scan (one-time)"]
        A[(Codebase)] --> B[codenav_scan]
        B --> C[.codenav.json index]
    end

    subgraph USE["Step 2: Use"]
        D[codenav_search] --> E[file:line locations]
        E --> F[codenav_read]
        F --> G[Only needed code]
    end

    C --> D

1. Scan once - Creates .codenav.json with all symbols indexed
2. Search by name - Find functions/classes/methods instantly
3. Read surgically - Load only the lines you need

While the primary use case is via MCP, you can also use the CLI directly:

# Generate code map (scan is an alias for map)
codenav scan .
codenav map .

# Search for symbols
codenav search "process_payment"

# Search by type
codenav search -t class -o table

# Search for files
codenav search --files "models" -o table

# Read specific lines
codenav read src/payments.py 45-89

# Read with context lines
codenav read src/payments.py 45-89 -c 3

# Get file structure
codenav search --structure src/payments.py

# Get symbol dependencies
codenav search --deps process_payment

# Get codebase stats
codenav stats

# Check if map needs updating
codenav search --check-stale

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

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

# Using uv
uv pip install "codenav @ git+https://github.com/efrenbl/code-navigator.git"

# Using pipx (isolated environment)
pipx install "git+https://github.com/efrenbl/code-navigator.git"

If you have multiple Python installations:

{
  "mcpServers": {
    "codenav": {
      "command": "python",
      "args": ["-m", "codenav.mcp"]
    }
  }
}

{
  "mcpServers": {
    "codenav": {
      "command": "codenav-mcp",
      "args": ["--workspace", "/path/to/your/project"]
    }
  }
}

*Install tree-sitter support: pip install "codenav[ast] @ git+https://github.com/efrenbl/code-navigator.git" 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 (the per-file imports key in the map). All except JS/TS also capture leading doc comments. Each symbol records which engine produced it ("source": "ast" | "ast-grep" | "regex").

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.

codenav map reports how much of a tree it actually mapped. The scan stats include files_processed, files_unmapped (with a per-extension breakdown in unmapped_extensions), files_skipped (ignored), symbols_truncated and a coverage_pct. The CLI prints a one-line summary, e.g.:

Coverage: mapped 636 · unmapped 12 (.kt:8 .sh:4) · skipped 1204 · coverage 98.2%

Use it to spot languages you're missing (a big .cs/.kt bucket) or an ignore pattern that's eating real source. The per-symbol cap for the regex analyzer is configurable with --max-symbol-lines (default 500) when large functions are being truncated.

Dart files are analyzed via regex out-of-the-box (classes, mixins, enums, extensions, top-level functions). To enable AST-level analysis (parented methods, constructors, accurate signatures), install the tree-sitter extra:

pip install "codenav[ast] @ git+https://github.com/efrenbl/code-navigator.git"

The Dart grammar ships pre-compiled inside tree-sitter-language-pack — no C compiler or manual build step required — and loads through the standard tree-sitter interface, exactly like the other languages. Flutter needs no separate grammar: Flutter widgets are ordinary Dart classes. [dart] is kept as a deprecated alias of [ast]; if no grammar is installed, codenav transparently falls back to the regex analyzer.

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

• Python 3.10+
• MCP SDK 1.0+

MIT License - see LICENSE for details.

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