Colby McHenryandClaude Opus 4.5
0c168c4d8b
- Add codegraph_explore MCP tool for deep exploration with condensed output - Expand default exclude patterns for framework build outputs (.next, .nuxt, .expo, etc.) - Increase node ID hash length from 16 to 32 chars to prevent collisions - Add feature request detection with UX clarification reminders - Update README with MCP tools reference and best practices - Update CLAUDE.md with context usage guidelines Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
164 lines
6.9 KiB
Markdown
164 lines
6.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
├── 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
|
|
|
|
### 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
|
|
|
|
```bash
|
|
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
|
|
|
|
When using CodeGraph MCP tools, follow these guidelines to minimize context usage:
|
|
|
|
### For Complex Tasks (features, refactoring, architecture)
|
|
Use `codegraph_explore` - it does intensive exploration internally and returns a condensed brief:
|
|
```
|
|
codegraph_explore(task: "implement user authentication with OAuth")
|
|
```
|
|
This replaces multiple tool calls and keeps your main context clean.
|
|
|
|
### For Simple Lookups
|
|
Use targeted tools directly:
|
|
- `codegraph_search` - Find symbols by name
|
|
- `codegraph_node` - Get details about one symbol
|
|
- `codegraph_callers/callees` - Understand usage patterns
|
|
|
|
### Context Usage Comparison
|
|
| Approach | Context Impact |
|
|
|----------|---------------|
|
|
| Multiple `codegraph_*` calls | High - each result stays in context |
|
|
| Single `codegraph_explore` | Low - returns condensed summary |
|
|
|
|
### 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.
|