CodeGraph (code-relation-graph)

A CLI tool that parses your source code and builds an interactive graph of relations between files, functions, and classes. Helps humans and AI agents understand code structure — what calls what, what imports what, and where things live.

Quick start

# Install globally
npm install -g @justin26l/codegraph

# build code graph (parse + html + export)
codegraph build ./path-to-project/src

Other usage

# Parse project to nodes
codegraph parse ./my-project --languages ts

# Generate interactive HTML visualization
codegraph html ./my-project -o graph.html
# Open graph.html in any browser

# Export graph as JSON (for AI agents / programmatic use)
codegraph export ./my-project -o graph.json

# Show graph statistics
codegraph stats ./my-project

Commands

Command	Description
parse	Parse source files and build graph database
html	Generate interactive HTML visualization
export	Export graph as JSON
stats	Show node/edge counts by type

Options

Flag	Default	Description
--languages	ts	Comma-separated languages (ts, py, go)
--exclude	**/*.test.*,node_modules/**	Exclude patterns
--include	—	Restrict parsing to specific paths
-o, --output	—	Output file path

What it does

• Parses TypeScript/JavaScript (Python/Go planned) using tree-sitter
• Builds a graph with: files, directories, classes, functions/methods
• Resolves cross-file calls — when auth.login() is called in index.ts, the edge points to the actual login method in auth.ts
• Tracks file-to-file imports
• Generates a self-contained HTML file (no server, no build step) with an interactive vis-network visualization

HTML visualization features

• Hierarchical layout (default) — directories at top, files below, functions at bottom
• Force-directed layout — switch via dropdown
• Search — filter nodes by name in real-time
• Type filter — show/hide directories, files, classes, functions
• Edge toggles — show/hide CONTAINS, CALLS, IMPORTS edges
• Focus mode — click a node to dim everything except its neighbors; double-click to restore
• Click any node to see its file path, line range, and type

Language support

Language	Status
TypeScript / JavaScript	✅ Working
Python	⏳ Grammar installed, adapter not yet written
Go	⏳ Grammar installed, adapter not yet written

Example

# Parse a project
codegraph parse ~/projects/my-app --languages ts --include "src/**"

# Open the visual graph
codegraph html ~/projects/my-app
open graph.html

# Feed the JSON to an AI agent
codegraph export ~/projects/my-app | pbcopy