@optave/codegraph

codegraph

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

Quick Start • Features • Commands • Languages • AI Integration • CI/CD • 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.

🚀 Quick Start

# Install
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 code search
👀	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 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

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
nomic	nomic-embed-text-v1	768	~137 MB	Apache-2.0	Best quality, 8192 context

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

🌐 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
	.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 (WASM) parses every source file into an AST
• 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

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 has a codegraph database 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`

🔁 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
  }
}

📖 Programmatic API

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

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

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

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

⚠️ 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

🤝 Contributing

Contributions are welcome! Here's how to get started:

git clone https://github.com/optave/codegraph.git
cd codegraph
npm install --legacy-peer-deps
npm test                # run tests with vitest

• Fork the repo
• Create your feature branch (git checkout -b feat/amazing-feature)
• Commit your changes
• Push to the branch
• Open a Pull Request

📄 License

Apache-2.0

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