`bash
codegraph # Run installer (when no args)
codegraph install # Run installer (explicit)
npx @mduenas/codegraph # Run via npx (no global install needed)
`

The installer will:
1. Ask for installation location (global ~/.claude or local ./.claude)
2. Configure the MCP server in claude.json
3. Optionally set up auto-allow permissions
4. Add global instructions to ~/.claude/CLAUDE.md (teaches Claude how to use CodeGraph)
5. For local installs: initialize and index the current project

$3

Initialize CodeGraph in a project directory. Creates a .codegraph/ directory with the database and configuration.

`bash
codegraph init # Initialize in current directory
codegraph init /path/to/project # Initialize in specific directory
codegraph init --index # Initialize and immediately index
codegraph init --no-hooks # Skip git hook installation
`

$3

Index all files in the project. Extracts functions, classes, methods, and their relationships.

`bash
codegraph index # Index current directory
codegraph index --force # Force full re-index
codegraph index --quiet # Suppress progress output
`

$3

Incrementally sync changes since the last index. Only processes added, modified, or removed files.

`bash
codegraph sync # Sync current directory
codegraph sync --quiet # Suppress output
`

$3

Show index status and statistics.

`bash
codegraph status
`

Output includes:
- Files indexed, nodes, edges
- Nodes by kind (functions, classes, methods, etc.)
- Files by language
- Pending changes (if any)
- Git hook status

$3

Search for symbols in the codebase by name.

`bash
codegraph query "authenticate" # Search for symbols
codegraph query "User" --kind class # Filter by kind
codegraph query "process" --limit 20 # Limit results
codegraph query "validate" --json # Output as JSON
`

$3

Build relevant code context for a task. Uses semantic search to find entry points, then expands through the graph to find related code.

`bash
codegraph context "fix checkout bug"
codegraph context "add user authentication" --format json
codegraph context "refactor payment service" --max-nodes 30
`

$3

Manage git hooks for automatic syncing.

`bash
codegraph hooks install # Install post-commit hook
codegraph hooks remove # Remove hook
codegraph hooks status # Check if hook is installed
`

$3

Start CodeGraph as an MCP server for AI assistants.

`bash
codegraph serve # Show MCP configuration help
codegraph serve --mcp # Start MCP server (stdio)
codegraph serve --mcp --path /project # Specify project path
`

🔌 MCP Tools Reference

When running as an MCP server, CodeGraph exposes these tools to AI assistants. These tools are designed to be used by Claude's Explore agents for faster, more efficient codebase exploration.

$3

Build context for a specific task. Good for focused queries.

`
codegraph_context(task: "fix checkout validation bug", maxNodes: 20)
`

$3

Quick symbol search by name. Returns locations only.

`
codegraph_search(query: "UserService", kind: "class", limit: 10)
`

$3

Find what calls a function, or what a function calls.

`
codegraph_callers(symbol: "validatePayment", limit: 20)
codegraph_callees(symbol: "processOrder", limit: 20)
`

$3

Analyze what code would be affected by changing a symbol.

`
codegraph_impact(symbol: "UserService", depth: 2)
`

$3

Get details about a specific symbol. Use includeCode: true only when needed.

`
codegraph_node(symbol: "authenticate", includeCode: true)
`

$3

Check index health and statistics.

$3

Claude's Explore agents use these tools instead of grep/glob/Read for faster exploration:

| Without CodeGraph | With CodeGraph | Benefit |
|-------------------|----------------|---------|
| grep -r "auth" | codegraph_search("auth") | Instant symbol lookup |
| Multiple Read calls | codegraph_context(task) | Related code in one call |
| Manual file tracing | codegraph_callers/callees | Call graph traversal |
| Guessing impact | codegraph_impact(symbol) | Know what breaks |

This hybrid approach gives you ~30% fewer tokens and ~25% fewer tool calls while letting Claude's native agents handle synthesis.

📚 Library Usage

CodeGraph can also be used as a library in your Node.js applications:

`typescript
import CodeGraph from '@mduenas/codegraph';

// Initialize a new project
const cg = await CodeGraph.init('/path/to/project');

// Or open an existing one
const cg = await CodeGraph.open('/path/to/project');

// Index with progress callback
await cg.indexAll({
onProgress: (progress) => {
console.log(${progress.phase}: ${progress.current}/${progress.total});
}
});

// Search for symbols
const results = cg.searchNodes('UserService');

// Get callers of a function
const node = results[0].node;
const callers = cg.getCallers(node.id);

// Build context for a task
const context = await cg.buildContext('fix login bug', {
maxNodes: 20,
includeCode: true,
format: 'markdown'
});

// Get impact radius
const impact = cg.getImpactRadius(node.id, 2);

// Sync changes
const syncResult = await cg.sync();

// Clean up
cg.close();
`

⚙️ How It Works

$3

CodeGraph uses tree-sitter to parse source code into ASTs. Language-specific queries (.scm files) extract:

- Nodes: Functions, methods, classes, interfaces, types, variables
- Edges: Calls, imports, extends, implements, returns_type

Each node gets a unique ID based on its kind, file path, name, and line number.

$3

All data is stored in a local SQLite database (.codegraph/codegraph.db):

- nodes table: All code entities with metadata
- edges table: Relationships between nodes
- files table: File tracking for incremental updates
- node_vectors / vector_map: Embeddings for semantic search (using sqlite-vss)

$3

After extraction, CodeGraph resolves references:

1. Match function calls to function definitions
2. Resolve imports to their source files
3. Link class inheritance and interface implementations
4. Apply framework-specific patterns (Express routes, etc.)

$3

CodeGraph uses local embeddings (via @xenova/transformers) to enable semantic search:

1. Code symbols are embedded using a transformer model
2. Queries are embedded and compared using cosine similarity
3. Results are ranked by relevance

$3

The graph structure enables powerful queries:

- Callers/Callees: Direct call relationships
- Impact Radius: BFS traversal to find all potentially affected code
- Dependencies: What a symbol depends on
- Dependents: What depends on a symbol

$3

When you request context for a task:

1. Semantic search finds relevant entry points
2. Graph traversal expands to related code
3. Code snippets are extracted
4. Results are formatted for AI consumption

⚙️ Configuration

The .codegraph/config.json file controls indexing behavior:

`json
{
"version": 1,
"projectName": "my-project",
"languages": ["typescript", "javascript"],
"exclude": [
"node_modules/**",
"dist/**",
"build/**",
"*.min.js"
],
"frameworks": ["express", "react"],
"maxFileSize": 1048576,
"gitHooksEnabled": true
}
`

$3

| Option | Description | Default |
|--------|-------------|---------|
| languages | Languages to index (auto-detected if empty) | [] |
| exclude | Glob patterns to ignore | ["node_modules/**", ...] |
| frameworks | Framework hints for better resolution | [] |
| maxFileSize | Skip files larger than this (bytes) | 1048576 (1MB) |
| gitHooksEnabled | Enable git hook installation | true |

🌐 Supported Languages

| Language | Extension | Status |
|----------|-----------|--------|
| TypeScript | .ts, .tsx | Full support |
| JavaScript | .js, .jsx, .mjs | Full support |
| Python | .py | Full support |
| Go | .go | Full support |
| Rust | .rs | Full support |
| Java | .java | Full support |
| C# | .cs | Full support |
| PHP | .php | Full support |
| Ruby | .rb | Full support |
| C | .c, .h | Full support |
| C++ | .cpp, .hpp, .cc | Full support |
| Swift | .swift | Full support |
| Kotlin | .kt, .kts | Full support |

🔧 Troubleshooting

$3

Run codegraph init in your project directory first.

$3

- Check if node_modules or other large directories are excluded
- Use --quiet flag to reduce console output overhead
- Consider increasing maxFileSize if you have large files to skip

$3

1. Ensure the project is initialized and indexed
2. Check the path in your MCP configuration is correct
3. Verify codegraph serve --mcp works from the command line
4. Check Claude Code logs for connection errors

$3

- Run codegraph sync` to pick up recent changes
- Check if the file's language is supported
- Verify the file isn't excluded by config patterns

---

📄 License

MIT

---