codegraph/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

CodeGraph is a local-first code intelligence system that builds a semantic knowledge graph from any codebase. It provides structural understanding of code relationships using tree-sitter for AST parsing and SQLite for storage.

Key characteristics:

• Headless library (no UI) - purely an API
• Node.js runtime (works standalone, in Electron, or any Node environment)
• Per-project data stored in .codegraph/ directory
• Deterministic extraction from AST, not AI-generated summaries

Build and Development Commands

# Build
npm run build          # Compile TypeScript and copy assets

# Test
npm test               # Run all tests once
npm run test:watch     # Run tests in watch mode

# Clean
npm run clean          # Remove dist/ directory

Running a Single Test

npx vitest run __tests__/extraction.test.ts           # Run specific test file
npx vitest run __tests__/extraction.test.ts -t "TypeScript"  # Run tests matching pattern

Architecture

Core Module Structure

src/
├── index.ts              # Main CodeGraph class - public API entry point
├── types.ts              # All TypeScript interfaces and types
├── db/                   # SQLite database layer
│   ├── index.ts          # DatabaseConnection class
│   ├── queries.ts        # QueryBuilder with prepared statements
│   └── schema.sql        # Table definitions with FTS5 search
├── extraction/           # Tree-sitter AST parsing
│   ├── index.ts          # ExtractionOrchestrator
│   ├── tree-sitter.ts    # Universal parser wrapper
│   └── grammars.ts       # Language detection and grammar loading
├── resolution/           # Reference resolver
│   ├── index.ts          # ReferenceResolver orchestrator
│   ├── import-resolver.ts
│   ├── name-matcher.ts
│   └── frameworks/       # Framework-specific patterns (React, Express, Laravel, etc.)
├── graph/                # Graph traversal and queries
│   ├── index.ts          # GraphQueryManager
│   ├── traversal.ts      # GraphTraverser (BFS/DFS, impact radius)
│   └── queries.ts        # High-level graph queries
├── vectors/              # Semantic search with embeddings
│   ├── index.ts          # VectorManager
│   ├── embedder.ts       # ONNX runtime + model loading
│   └── search.ts         # Similarity search
├── context/              # Context building for AI assistants
│   ├── index.ts          # ContextBuilder
│   └── formatter.ts      # Markdown/JSON output formatting
├── sync/                 # Incremental update system
│   ├── index.ts
│   └── git-hooks.ts      # Post-commit hook management
├── installer/            # Interactive installer
│   ├── index.ts          # Installer orchestrator
│   ├── banner.ts         # ASCII art banner
│   ├── claude-md-template.ts # CLAUDE.md template generator
│   ├── config-writer.ts  # Configuration file writing
│   └── prompts.ts        # User prompts
├── mcp/                  # Model Context Protocol server
│   ├── index.ts          # MCPServer class
│   ├── tools.ts          # MCP tool definitions
│   └── transport.ts      # Stdio transport
└── bin/codegraph.ts      # CLI entry point

Key Classes

• CodeGraph (src/index.ts): Main entry point. Lifecycle methods (init, open, close), indexing (indexAll, sync), graph queries (traverse, getCallGraph, getImpactRadius), semantic search (semanticSearch, findSimilar), context building (buildContext)

• ExtractionOrchestrator (src/extraction/index.ts): Coordinates file scanning, parsing, and storing. Uses tree-sitter native bindings for each supported language

• GraphTraverser (src/graph/traversal.ts): BFS/DFS traversal, call graph construction, impact radius calculation, path finding

• VectorManager (src/vectors/manager.ts): Manages embeddings using @xenova/transformers for ONNX inference. Stores vectors in SQLite BLOB format

• ReferenceResolver (src/resolution/index.ts): Resolves unresolved references after full indexing using framework patterns, import resolution, and name matching

Database Schema

SQLite database with:

• nodes: Code symbols (functions, classes, methods, etc.)
• edges: Relationships (calls, imports, extends, contains, etc.)
• files: Tracked source files with content hashes
• unresolved_refs: References pending resolution
• vectors: Embeddings stored as BLOBs
• nodes_fts: FTS5 virtual table for full-text search

Supported Languages

TypeScript, JavaScript, TSX, JSX, Python, Go, Rust, Java, C, C++, C#, PHP, Ruby, Swift, Kotlin, Dart, Liquid, Pascal

Node and Edge Types

NodeKind: file, module, class, struct, interface, trait, protocol, function, method, property, field, variable, constant, enum, enum_member, type_alias, namespace, parameter, import, export, route, component

EdgeKind: contains, calls, imports, exports, extends, implements, references, type_of, returns, instantiates, overrides, decorates

CLI Usage

codegraph init [path]       # Initialize in project
codegraph index [path]      # Full index
codegraph sync [path]       # Incremental update
codegraph status [path]     # Show statistics
codegraph query <search>    # Search symbols
codegraph context <task>    # Build context for AI
codegraph hooks install     # Install git auto-sync
codegraph serve --mcp       # Start MCP server

MCP Tools Best Practices

Use these tools directly in the main session for fast code exploration (replaces the need for Explore agents in most cases):

Tool	Use For
codegraph_explore	Deep exploration — comprehensive context for a topic in ONE call
codegraph_context	Quick context for a task (lighter than explore)
codegraph_search	Find symbols by name (functions, classes, types)
codegraph_callers	Find what calls a function
codegraph_callees	Find what a function calls
codegraph_impact	See what's affected by changing a symbol
codegraph_node	Get details + source code for a symbol

Important

CodeGraph provides code context, not product requirements. For new features, still ask the user about:

• UX preferences and behavior
• Edge cases and error handling
• Acceptance criteria

Test Structure

Tests are in __tests__/ directory with files mirroring the module structure:

• foundation.test.ts - Database, config, directory management
• extraction.test.ts - Tree-sitter parsing for all languages
• resolution.test.ts - Reference resolution
• graph.test.ts - Traversal and graph queries
• vectors.test.ts - Embedding and semantic search
• context.test.ts - Context building
• sync.test.ts - Incremental updates and git hooks

Tests use temporary directories created with fs.mkdtempSync and cleaned up after each test.