@optave/codegraph

codegraph

Local code dependency graph CLI — parse, query, and visualize your codebase at file and function level.

Why codegraph? • Quick Start • Features • Commands • Languages • AI Integration • Practices • CI/CD • Roadmap • Contributing

Zero network calls. Zero telemetry. Your code never leaves your machine.

Codegraph uses tree-sitter (via WASM — no native compilation required) to parse your codebase into an AST, extracts functions, classes, imports, and call sites, resolves dependencies, and stores everything in a local SQLite database. Query it instantly from the command line.

💡 Why codegraph?

_{Comparison last verified: February 2026}

Most dependency graph tools only tell you which files import which — codegraph tells you which functions call which, who their callers are, and what breaks when something changes. Here's how it compares to the alternatives:

Feature comparison

Capability	codegraph	Madge	dep-cruiser	Skott	Nx graph	Sourcetrail
Function-level analysis	Yes	—	—	—	—	Yes
Multi-language	10	1	1	1	Any (project)	4
Semantic search	Yes	—	—	—	—	—
MCP / AI agent support	Yes	—	—	—	—	—
Git diff impact	Yes	—	—	—	Partial	—
Persistent database	Yes	—	—	—	—	Yes
Watch mode	Yes	—	—	—	Daemon	—
CI workflow included	Yes	—	Rules	—	Yes	—
Cycle detection	Yes	Yes	Yes	Yes	—	—
Zero config	Yes	Yes	—	Yes	—	—
Fully local / no telemetry	Yes	Yes	Yes	Yes	Partial	Yes
Free & open source	Yes	Yes	Yes	Yes	Partial	Archived

What makes codegraph different

	Differentiator	In practice
🔬	Function-level, not just files	Traces handleAuth() → validateToken() → decryptJWT() and shows 14 callers across 9 files break if decryptJWT changes
🌐	Multi-language, one CLI	JS/TS + Python + Go + Rust + Java + C# + PHP + Ruby + Terraform in a single graph — no juggling Madge, pyan, and cflow
🤖	AI-agent ready	Built-in MCP server — AI assistants query your graph directly via codegraph fn <name>
💥	Git diff impact	codegraph diff-impact shows changed functions, their callers, and full blast radius — ships with a GitHub Actions workflow
🔒	Fully local, zero telemetry	No accounts, no API keys, no cloud, no data exfiltration — Apache-2.0, free forever
⚡	Build once, query instantly	SQLite-backed — build in ~30s, every query under 100ms. Native Rust engine with WASM fallback. Most competitors re-parse every run
🧠	Semantic search	codegraph search "handle auth" uses local embeddings — multi-query with RRF ranking via "auth; token; JWT"

How other tools compare

Many tools in this space are cloud-based or SaaS — meaning your code leaves your machine. Others require external services, accounts, or API keys. Codegraph makes zero network calls and has zero telemetry. Everything runs locally.

Tool	What it does well	Where it falls short
Madge	Simple file-level JS/TS dependency graphs	No function-level analysis, no impact tracing, JS/TS only
dependency-cruiser	Architectural rule validation for JS/TS	Module-level only (function-level explicitly out of scope), requires config
Skott	Module graph with unused code detection	File-level only, JS/TS only, no persistent database
Nx graph	Monorepo project-level dependency graph	Requires Nx workspace, project-level only (not file or function)
Sourcetrail	Rich GUI with symbol-level graphs	Archived/discontinued (2021), no JS/TS, no CLI
Sourcegraph	Enterprise code search and navigation	Cloud/SaaS — code sent to servers, $19+/user/mo, no longer open source
CodeSee	Visual codebase maps	Cloud-based — code leaves your machine, acquired by GitKraken
Understand	Deep multi-language static analysis	$100+/month per seat, proprietary, GUI-only, no CI or AI integration
Snyk Code	AI-powered security scanning	Cloud-based — code sent to Snyk servers for analysis, not a dependency graph tool
pyan / cflow	Function-level call graphs	Single-language each (Python / C only), no persistence, no queries

🚀 Quick Start

# Install from npm
npm install -g @optave/codegraph

# Or install from source
git clone https://github.com/optave/codegraph.git
cd codegraph
npm install
npm link

# Build a graph for any project
cd your-project
codegraph build        # → .codegraph/graph.db created

# Start exploring
codegraph map          # see most-connected files
codegraph query myFunc # find any function, see callers & callees
codegraph deps src/index.ts  # file-level import/export map

✨ Features

	Feature	Description
🔍	Symbol search	Find any function, class, or method by name with callers/callees
📁	File dependencies	See what a file imports and what imports it
💥	Impact analysis	Trace every file affected by a change (transitive)
🧬	Function-level tracing	Call chains, caller trees, and function-level impact
📊	Diff impact	Parse git diff, find overlapping functions, trace their callers
🗺️	Module map	Bird's-eye view of your most-connected files
🔄	Cycle detection	Find circular dependencies at file or function level
📤	Export	DOT (Graphviz), Mermaid, and JSON graph export
🧠	Semantic search	Embeddings-powered natural language search with multi-query RRF ranking
👀	Watch mode	Incrementally update the graph as files change
🤖	MCP server	Model Context Protocol integration for AI assistants
🔒	Fully local	No network calls, no data exfiltration, SQLite-backed

📦 Commands

Build & Watch

codegraph build [dir]          # Parse and build the dependency graph
codegraph build --no-incremental  # Force full rebuild
codegraph build --engine wasm  # Force WASM engine (skip native)
codegraph watch [dir]          # Watch for changes, update graph incrementally

Query & Explore

codegraph query <name>         # Find a symbol — shows callers and callees
codegraph deps <file>          # File imports/exports
codegraph map                  # Top 20 most-connected files
codegraph map -n 50            # Top 50

Impact Analysis

codegraph impact <file>        # Transitive reverse dependency trace
codegraph fn <name>            # Function-level: callers, callees, call chain
codegraph fn <name> --no-tests --depth 5
codegraph fn-impact <name>     # What functions break if this one changes
codegraph diff-impact          # Impact of unstaged git changes
codegraph diff-impact --staged # Impact of staged changes
codegraph diff-impact HEAD~3   # Impact vs a specific ref

Export & Visualization

codegraph export -f dot        # Graphviz DOT format
codegraph export -f mermaid    # Mermaid diagram
codegraph export -f json       # JSON graph
codegraph export --functions -o graph.dot  # Function-level, write to file
codegraph cycles               # Detect circular dependencies
codegraph cycles --functions   # Function-level cycles

Semantic Search

Codegraph can build local embeddings for every function, method, and class, then search them by natural language. Everything runs locally using @huggingface/transformers — no API keys needed.

codegraph embed                # Build embeddings (default: minilm)
codegraph embed --model nomic  # Use a different model
codegraph search "handle authentication"
codegraph search "parse config" --min-score 0.4 -n 10
codegraph models               # List available models

Multi-query search

Separate queries with ; to search from multiple angles at once. Results are ranked using Reciprocal Rank Fusion (RRF) — items that rank highly across multiple queries rise to the top.

codegraph search "auth middleware; JWT validation"
codegraph search "parse config; read settings; load env" -n 20
codegraph search "error handling; retry logic" --kind function
codegraph search "database connection; query builder" --rrf-k 30

A single trailing semicolon is ignored (falls back to single-query mode). The --rrf-k flag controls the RRF smoothing constant (default 60) — lower values give more weight to top-ranked results.

Available Models

Flag	Model	Dimensions	Size	License	Notes
minilm (default)	all-MiniLM-L6-v2	384	~23 MB	Apache-2.0	Fastest, good for quick iteration
jina-small	jina-embeddings-v2-small-en	512	~33 MB	Apache-2.0	Better quality, still small
jina-base	jina-embeddings-v2-base-en	768	~137 MB	Apache-2.0	High quality, 8192 token context
jina-code	jina-embeddings-v2-base-code	768	~137 MB	Apache-2.0	Best for code search, trained on code+text
nomic	nomic-embed-text-v1	768	~137 MB	Apache-2.0	Good quality, 8192 context
nomic-v1.5	nomic-embed-text-v1.5	768	~137 MB	Apache-2.0	Improved nomic, Matryoshka dimensions
bge-large	bge-large-en-v1.5	1024	~335 MB	MIT	Best general retrieval, top MTEB scores

The model used during embed is stored in the database, so search auto-detects it — no need to pass --model when searching.

AI Integration

codegraph mcp                  # Start MCP server for AI assistants

Common Flags

Flag	Description
-d, --db <path>	Custom path to graph.db
-T, --no-tests	Exclude .test., .spec., __test__ files
--depth <n>	Transitive trace depth (default varies by command)
-j, --json	Output as JSON
-v, --verbose	Enable debug output
--engine <engine>	Parser engine: native, wasm, or auto (default: auto)
-k, --kind <kind>	Filter by kind: function, method, class (search)
--file <pattern>	Filter by file path pattern (search)
--rrf-k <n>	RRF smoothing constant for multi-query search (default 60)

🌐 Language Support

Language	Extensions	Coverage
	.js, .jsx, .mjs, .cjs	Full — functions, classes, imports, call sites
	.ts, .tsx	Full — interfaces, type aliases, .d.ts
	.py	Functions, classes, methods, imports, decorators
	.go	Functions, methods, structs, interfaces, imports, call sites
	.rs	Functions, methods, structs, traits, use imports, call sites
	.java	Classes, methods, constructors, interfaces, imports, call sites
	.cs	Classes, structs, records, interfaces, enums, methods, constructors, using directives, invocations
	.php	Functions, classes, interfaces, traits, enums, methods, namespace use, calls
	.rb	Classes, modules, methods, singleton methods, require/require_relative, include/extend
	.tf, .hcl	Resource, data, variable, module, output blocks

⚙️ How It Works

┌──────────┐    ┌───────────┐    ┌───────────┐    ┌──────────┐    ┌─────────┐
│  Source  │──▶│ tree-sitter│──▶│  Extract  │──▶│  Resolve │──▶│ SQLite  │
│  Files   │    │   Parse   │    │  Symbols  │    │  Imports │    │   DB    │
└──────────┘    └───────────┘    └───────────┘    └──────────┘    └─────────┘
                                                                       │
                                                                       ▼
                                                                 ┌─────────┐
                                                                 │  Query  │
                                                                 └─────────┘

• Parse — tree-sitter parses every source file into an AST (native Rust engine or WASM fallback)
• Extract — Functions, classes, methods, interfaces, imports, exports, and call sites are extracted
• Resolve — Imports are resolved to actual files (handles ESM conventions, tsconfig.json path aliases, baseUrl)
• Store — Everything goes into SQLite as nodes + edges with tree-sitter node boundaries
• Query — All queries run locally against the SQLite DB — typically under 100ms

Dual Engine

Codegraph ships with two parsing engines:

Engine	How it works	When it's used
Native (Rust)	napi-rs addon built from crates/codegraph-core/ — parallel multi-core parsing via rayon	Auto-selected when the prebuilt binary is available
WASM	web-tree-sitter with pre-built .wasm grammars in grammars/	Fallback when the native addon isn't installed

Both engines produce identical output. Use --engine native|wasm|auto to control selection (default: auto).

Call Resolution

Calls are resolved with priority and confidence scoring:

Priority	Source	Confidence
1	Import-aware — import { foo } from './bar' → link to bar	1.0
2	Same-file — definitions in the current file	1.0
3	Same directory — definitions in sibling files	0.7
4	Same parent directory — definitions in sibling dirs	0.5
5	Global fallback — match by name across codebase	0.3
6	Method hierarchy — resolved through extends/implements	—

Dynamic patterns like fn.call(), fn.apply(), fn.bind(), and obj["method"]() are also detected on a best-effort basis.

📊 Performance

Benchmarked on a ~3,200-file TypeScript project:

Metric	Value
Build time	~30s
Nodes	19,000+
Edges	120,000+
Query time	<100ms
DB size	~5 MB

🤖 AI Agent Integration

MCP Server

Codegraph includes a built-in Model Context Protocol server, so AI assistants can query your dependency graph directly:

codegraph mcp

CLAUDE.md / Agent Instructions

Add this to your project's CLAUDE.md to help AI agents use codegraph:

## Code Navigation

This project uses codegraph. The database is at `.codegraph/graph.db`.

- **Before modifying a function**: `codegraph fn <name> --no-tests`
- **Before modifying a file**: `codegraph deps <file>`
- **To assess PR impact**: `codegraph diff-impact --no-tests`
- **To find entry points**: `codegraph map`
- **To trace breakage**: `codegraph fn-impact <name> --no-tests`

Rebuild after major structural changes: `codegraph build`

### Semantic search

Use `codegraph search` to find functions by intent rather than exact name.
When a single query might miss results, combine multiple angles with `;`:

  codegraph search "validate auth; check token; verify JWT"
  codegraph search "parse config; load settings" --kind function

Multi-query search uses Reciprocal Rank Fusion — functions that rank
highly across several queries surface first. This is especially useful
when you're not sure what naming convention the codebase uses.

When writing multi-queries, use 2-4 sub-queries (2-4 words each) that
attack the problem from different angles. Pick from these strategies:
- **Naming variants**: cover synonyms the author might have used
  ("send email; notify user; deliver message")
- **Abstraction levels**: pair high-level intent with low-level operation
  ("handle payment; charge credit card")
- **Input/output sides**: cover the read half and write half
  ("parse config; apply settings")
- **Domain + technical**: bridge business language and implementation
  ("onboard tenant; create organization; provision workspace")

Use `--kind function` to cut noise. Use `--file <pattern>` to scope.

📋 Recommended Practices

See docs/recommended-practices.md for integration guides:

• Git hooks — auto-rebuild on commit, impact checks on push, commit message enrichment
• CI/CD — PR impact comments, threshold gates, graph caching
• AI agents — MCP server, CLAUDE.md templates, Claude Code hooks
• Developer workflow — watch mode, explore-before-you-edit, semantic search
• Secure credentials — apiKeyCommand with 1Password, Bitwarden, Vault, macOS Keychain, pass

🔁 CI / GitHub Actions

Codegraph ships with a ready-to-use GitHub Actions workflow that comments impact analysis on every pull request.

Copy .github/workflows/codegraph-impact.yml to your repo, and every PR will get a comment like:

3 functions changed → 12 callers affected across 7 files

🛠️ Configuration

Create a .codegraphrc.json in your project root to customize behavior:

{
  "include": ["src/**", "lib/**"],
  "exclude": ["**/*.test.js", "**/__mocks__/**"],
  "ignoreDirs": ["node_modules", ".git", "dist"],
  "extensions": [".js", ".ts", ".tsx", ".py"],
  "aliases": {
    "@/": "./src/",
    "@utils/": "./src/utils/"
  },
  "build": {
    "incremental": true
  }
}

LLM credentials

Codegraph supports an apiKeyCommand field for secure credential management. Instead of storing API keys in config files or environment variables, you can shell out to a secret manager at runtime:

{
  "llm": {
    "provider": "openai",
    "apiKeyCommand": "op read op://vault/openai/api-key"
  }
}

The command is split on whitespace and executed with execFileSync (no shell injection risk). Priority: command output > CODEGRAPH_LLM_API_KEY env var > file config. On failure, codegraph warns and falls back to the next source.

Works with any secret manager: 1Password CLI (op), Bitwarden (bw), pass, HashiCorp Vault, macOS Keychain (security), AWS Secrets Manager, etc.

📖 Programmatic API

Codegraph also exports a full API for use in your own tools:

import { buildGraph, queryNameData, findCycles, exportDOT } from '@optave/codegraph';

// Build the graph
buildGraph('/path/to/project');

// Query programmatically
const results = queryNameData('myFunction', '/path/to/.codegraph/graph.db');

import { parseFileAuto, getActiveEngine, isNativeAvailable } from '@optave/codegraph';

// Check which engine is active
console.log(getActiveEngine());      // 'native' or 'wasm'
console.log(isNativeAvailable());    // true if Rust addon is installed

// Parse a single file (uses auto-selected engine)
const symbols = await parseFileAuto('/path/to/file.ts');

import { searchData, multiSearchData, buildEmbeddings } from '@optave/codegraph';

// Build embeddings (one-time)
await buildEmbeddings('/path/to/project');

// Single-query search
const { results } = await searchData('handle auth', dbPath);

// Multi-query search with RRF ranking
const { results: fused } = await multiSearchData(
  ['auth middleware', 'JWT validation'],
  dbPath,
  { limit: 10, minScore: 0.3 }
);
// Each result has: { name, kind, file, line, rrf, queryScores[] }

⚠️ Limitations

• No full type inference — parses .d.ts interfaces but doesn't use TypeScript's type checker for overload resolution
• Dynamic calls are best-effort — complex computed property access and eval patterns are not resolved
• Python imports — resolves relative imports but doesn't follow sys.path or virtual environment packages

🗺️ Roadmap

See ROADMAP.md for the full development roadmap. Current plan:

• Rust Core — Complete (v1.3.0) — native tree-sitter parsing via napi-rs, parallel multi-core parsing, incremental re-parsing, import resolution & cycle detection in Rust
• Foundation Hardening — Complete (v1.4.0) — parser registry, 11-tool MCP server, test coverage 62%→75%, apiKeyCommand secret resolution
• Intelligent Embeddings — LLM-generated descriptions, hybrid search
• Natural Language Queries — codegraph ask command, conversational sessions
• Expanded Language Support — 8 new languages (12 → 20)
• GitHub Integration & CI — reusable GitHub Action, PR review, SARIF output
• Visualization & Advanced — web UI, dead code detection, monorepo support, agentic search

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for the full guide — setup, workflow, commit convention, testing, and architecture notes.

git clone https://github.com/optave/codegraph.git
cd codegraph
npm install
npm test

Looking to add a new language? Check out Adding a New Language.

📄 License

Apache-2.0

_{Built with tree-sitter and better-sqlite3. No data leaves your machine. Ever.}