code-graph

High-performance code intelligence engine that indexes TypeScript/JavaScript codebases into a queryable dependency graph. Built in Rust, designed for AI agents.

Gives Claude Code direct access to your codebase's structure via MCP — no source file reading needed. Find symbols, trace references, analyze blast radius, and detect circular dependencies through pre-built graph queries.

Features

• Tree-sitter parsing — TypeScript, TSX, JavaScript, JSX with full symbol extraction (functions, classes, interfaces, types, enums, components, methods, properties)
• Dependency graph — file-level and symbol-level edges: imports, calls, extends, implements, type references
• Import resolution — TypeScript path aliases (tsconfig.json), barrel files (index.ts re-exports), monorepo workspaces
• Six query types — find definitions, trace references, blast radius analysis, circular dependency detection, 360-degree symbol context, project statistics
• MCP server — exposes all queries as tools for Claude Code over stdio
• File watcher — incremental re-indexing on file changes with 75ms debounce
• Disk cache — bincode serialization for instant cold starts
• Token-optimized output — compact format designed for AI agent consumption

Install

cargo install code-graph-cli

This installs the code-graph binary to ~/.cargo/bin/.

From source

git clone https://github.com/MonsieurBarti/code-graph-ai.git
cd code-graph-ai
cargo install --path .

Build manually

git clone https://github.com/MonsieurBarti/code-graph-ai.git
cd code-graph-ai
cargo build --release
# Binary at target/release/code-graph

Requires Rust 1.85+ (edition 2024). No runtime dependencies — tree-sitter grammars are statically linked.

Quick start

# Index a project
code-graph index /path/to/project

# Find a symbol
code-graph find "UserService" /path/to/project

# What breaks if I change this?
code-graph impact "DatabaseConfig" /path/to/project

# Start MCP server for Claude Code
code-graph mcp /path/to/project

CLI reference

Usage: code-graph <COMMAND>

Commands:
  index     Index a project directory
  find      Find a symbol's definition (file:line location)
  refs      Find all references to a symbol across the codebase
  impact    Show the transitive blast radius of changing a symbol
  circular  Detect circular dependencies in the import graph
  stats     Project statistics overview
  context   360-degree view of a symbol: definition, references, callers, callees
  mcp       Start an MCP stdio server exposing graph queries as tools
  watch     Start a file watcher for incremental re-indexing

index

Index a project, discovering and parsing all TypeScript/JavaScript files.

code-graph index . --verbose    # Print each discovered file
code-graph index . --json       # Output as JSON

find

Find symbol definitions by name or regex pattern.

code-graph find "UserService" .
code-graph find "User.*Service" . -i            # Case-insensitive regex
code-graph find "authenticate" . --kind function # Filter by kind
code-graph find "Button" . --file src/components # Scope to directory

Symbol kinds: function, class, interface, type, enum, variable, component, method, property

refs

Find all files and call sites that reference a symbol.

code-graph refs "UserService" .
code-graph refs "useAuth" . --format table    # Human-readable table

impact

Show the transitive blast radius — everything affected if a symbol changes.

code-graph impact "DatabaseConfig" .
code-graph impact "API" . --tree              # Hierarchical dependency chain

circular

Detect circular dependency cycles in the import graph (file-level).

code-graph circular .
code-graph circular . --format json

stats

Project overview: file count, symbol breakdown by kind, import summary.

code-graph stats .
code-graph stats . --format json

context

360-degree view combining definition, references, callers, and callees.

code-graph context "Logger" .

watch

Start a standalone file watcher that re-indexes incrementally on changes.

code-graph watch .

The mcp command starts its own embedded watcher automatically — you don't need to run watch separately.

Output formats

All query commands support --format:

MCP integration

Claude Code setup

Add to your Claude Code MCP config (~/.claude/claude_desktop_config.json or project .mcp.json):

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

Available tools

Once connected, Claude Code gets access to six tools:

The MCP server loads from disk cache on startup for near-instant cold starts, runs an embedded file watcher for live updates, and suggests similar symbol names when a search yields no results.

Recommended CLAUDE.md instructions

Claude Code defaults to reading source files with its built-in glob/grep/read tools. Without explicit guidance, it won't use code-graph even when the MCP server is running. Add the following to your project's CLAUDE.md so Claude uses graph queries instead of file reading for codebase navigation:

## Code navigation — MANDATORY

NEVER use Grep or Glob to find symbol definitions, trace references, or analyze dependencies.
ALWAYS use code-graph MCP tools instead — they are faster, more accurate, and understand the full AST.

| Task | Tool | NOT this |
|------|------|----------|
| Find where something is defined | `find_symbol` | ~~Grep for `class X`, `function X`, `fn X`~~ |
| Find what uses/imports something | `find_references` | ~~Grep for `import`, `require`, identifier~~ |
| Understand a symbol fully | `get_context` | ~~Multiple Grep + Read calls~~ |
| Check what breaks if I change X | `get_impact` | ~~Manual file-by-file tracing~~ |
| Detect circular deps | `detect_circular` | ~~Grep for import cycles~~ |
| Project overview | `get_stats` | ~~Glob + count files~~ |

Use Read/Grep/Glob ONLY for:
- Reading full file contents before editing
- Searching for string literals, comments, TODOs, error messages
- Non-structural text searches that have nothing to do with code navigation

Permission whitelisting

By default, Claude Code asks for confirmation on every MCP tool call. To auto-approve code-graph tools (they are read-only and safe), add this to .claude/settings.json in your project root:

{
  "permissions": {
    "allow": [
      "mcp__code-graph__find_symbol",
      "mcp__code-graph__find_references",
      "mcp__code-graph__get_impact",
      "mcp__code-graph__detect_circular",
      "mcp__code-graph__get_context",
      "mcp__code-graph__get_stats"
    ]
  }
}

Configuration

Optional code-graph.toml in your project root:

[exclude]
paths = ["vendor/", "dist/", "build/"]

By default, code-graph respects .gitignore patterns and always excludes node_modules/.

How it works

1. Walk — discovers TS/JS files respecting .gitignore and exclusion rules
2. Parse — tree-sitter extracts symbols, imports, exports, and relationships from each file
3. Resolve — maps import specifiers to actual files using oxc_resolver (handles path aliases, barrel files, workspaces)
4. Build graph — constructs a petgraph with file nodes, symbol nodes, and typed edges (imports, calls, extends, implements, type references)
5. Cache — serializes the graph to disk with bincode for fast reloads
6. Query — traverses the graph to answer structural questions without reading source files
7. Watch — monitors filesystem events and incrementally updates the graph (re-parses only changed files)