code-graph-rag

Supports Claude Code, Mcp

• PHP Language Support: Full PHP language support added — classes, interfaces, traits, enums, namespaces, PHP 8 attributes, and call graph analysis. Contributed by @rs-ipps.
• C Language Support: Full C language support added — functions, structs, unions, enums, preprocessor includes, and call graph analysis. Contributed by @dj0nes.
• Visualise any GitHub repo instantly! Just change github.com to gitcgr.com in any repo URL — that's it, only 3 letters! Get an interactive graph of the entire codebase structure. Try it now: gitcgr.com

• Multi-Language Support:

• 🌳 Tree-sitter Parsing: Uses Tree-sitter for robust, language-agnostic AST parsing
• 📊 Knowledge Graph Storage: Uses Memgraph to store codebase structure as an interconnected graph
• 🗣️ Natural Language Querying: Ask questions about your codebase in plain English
• 🤖 AI-Powered Cypher Generation: Supports both cloud models (Google Gemini), local models (Ollama), and OpenAI models for natural language to Cypher translation
• 🤖 OpenAI Integration: Leverage OpenAI models to enhance AI functionalities.
• 📝 Code Snippet Retrieval: Retrieves actual source code snippets for found functions/methods
• ✍️ Advanced File Editing: Surgical code replacement with AST-based function targeting, visual diff previews, and exact code block modifications
• ⚡️ Shell Command Execution: Can execute terminal commands for tasks like running tests or using CLI tools.
• 🚀 Interactive Code Optimization: AI-powered codebase optimization with language-specific best practices and interactive approval workflow
• 📚 Reference-Guided Optimization: Use your own coding standards and architectural documents to guide optimization suggestions
• 🧹 Dead Code Detection: Report functions and methods unreachable from any entry point by walking CALLS/REFERENCES edges from roots (with a CI-friendly --fail-on-found)
• 🔗 Dependency Analysis: Parses pyproject.toml to understand external dependencies
• 🎯 Nested Function Support: Handles complex nested functions and class hierarchies
• 🔄 Language-Agnostic Design: Unified graph schema across all supported languages

What it does:

• Watches your repository for file changes (create, modify, delete)
• Automatically updates the knowledge graph in real-time
• Maintains consistency by recalculating all function call relationships
• Filters out irrelevant files (.git, node_modules, etc.)

How to use:

Run the realtime updater in a separate terminal:

# Using Python directly
python realtime_updater.py /path/to/your/repo

# Or using the Makefile
make watch REPO_PATH=/path/to/your/repo

With custom Memgraph settings:

# Python
python realtime_updater.py /path/to/your/repo --host localhost --port 7687 --batch-size 1000

# Makefile
make watch REPO_PATH=/path/to/your/repo HOST=localhost PORT=7687 BATCH_SIZE=1000

Multi-terminal workflow:

# Terminal 1: Start the realtime updater
python realtime_updater.py ~/my-project

# Terminal 2: Run the AI assistant
cgr start --repo-path ~/my-project

Performance note: The updater currently recalculates all CALLS relationships on every file change to ensure consistency. This prevents "island" problems where changes in one file aren't reflected in relationships from other files, but may impact performance on very large codebases with frequent changes. Note: Optimization of this behavior is a work in progress.

CLI Arguments:

• repo_path (required): Path to repository to watch
• --host: Memgraph host (default: localhost)
• --port: Memgraph port (default: 7687)
• --batch-size: Number of buffered nodes/relationships before flushing to Memgraph

Specify Custom Models:

# Use specific local models
cgr start --repo-path /path/to/your/repo \
  --orchestrator ollama:llama3.2 \
  --cypher ollama:codellama

# Use specific Gemini models
cgr start --repo-path /path/to/your/repo \
  --orchestrator google:gemini-2.0-flash-thinking-exp-01-21 \
  --cypher google:gemini-2.5-flash-lite-preview-06-17

# Use mixed providers
cgr start --repo-path /path/to/your/repo \
  --orchestrator google:gemini-2.0-flash-thinking-exp-01-21 \
  --cypher ollama:codellama

Example queries (works across all supported languages):

• "Show me all classes that contain 'user' in their name"
• "Find functions related to database operations"
• "What methods does the User class have?"
• "Show me functions that handle authentication"
• "List all TypeScript components"
• "Find Rust structs and their methods"
• "Show me Go interfaces and implementations"
• "Find all C++ operator overloads in the Matrix class"
• "Show me C++ template functions with their specializations"
• "List all C++ namespaces and their contained classes"
• "Find C++ lambda expressions used in algorithms"
• "Add logging to all database connection functions"
• "Refactor the User class to use dependency injection"
• "Convert these Python functions to async/await pattern"
• "Add error handling to authentication methods"
• "Optimize this function for better performance"

Step 3: Export Graph Data

For programmatic access and integration with other tools, you can export the entire knowledge graph to JSON:

Export during graph update:

cgr start --repo-path /path/to/repo --update-graph --clean -o my_graph.json

Export existing graph without updating:

cgr export -o my_graph.json

Optional: adjust Memgraph batching during export:

cgr export -o my_graph.json --batch-size 5000

Working with exported data:

from codebase_rag.graph_loader import load_graph

# Load the exported graph
graph = load_graph("my_graph.json")

# Get summary statistics
summary = graph.summary()
print(f"Total nodes: {summary['total_nodes']}")
print(f"Total relationships: {summary['total_relationships']}")

# Find specific node types
functions = graph.find_nodes_by_label("Function")
classes = graph.find_nodes_by_label("Class")

# Analyze relationships
for func in functions[:5]:
    relationships = graph.get_relationships_for_node(func.node_id)
    print(f"Function {func.properties['name']} has {len(relationships)} relationships")

Example analysis script:

python examples/graph_export_example.py my_graph.json

This provides a reliable, programmatic way to access your codebase structure without LLM restrictions, perfect for:

• Integration with other tools
• Custom analysis scripts
• Building documentation generators
• Creating code metrics dashboards

Step 4: Code Optimization

For AI-powered codebase optimization with best practices guidance:

Basic optimization for a specific language:

cgr optimize python --repo-path /path/to/your/repo

Optimization with reference documentation:

cgr optimize python \
  --repo-path /path/to/your/repo \
  --reference-document /path/to/best_practices.md

Using specific models for optimization:

cgr optimize javascript \
  --repo-path /path/to/frontend \
  --orchestrator google:gemini-2.0-flash-thinking-exp-01-21

# Optional: override Memgraph batch flushing during optimization
cgr optimize javascript --repo-path /path/to/frontend \
  --batch-size 5000

Supported Languages for Optimization: All supported languages: python, javascript, typescript, rust, go, java, scala, c, cpp

How It Works:

1. Analysis Phase: The agent analyzes your codebase structure using the knowledge graph
2. Pattern Recognition: Identifies common anti-patterns, performance issues, and improvement opportunities
3. Best Practices Application: Applies language-specific best practices and patterns
4. Interactive Approval: Presents each optimization suggestion for your approval before implementation
5. Guided Implementation: Implements approved changes with detailed explanations

Example Optimization Session:

Starting python optimization session...
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ The agent will analyze your python codebase and propose specific          ┃
┃ optimizations. You'll be asked to approve each suggestion before          ┃
┃ implementation. Type 'exit' or 'quit' to end the session.                 ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

🔍 Analyzing codebase structure...
📊 Found 23 Python modules with potential optimizations

💡 Optimization Suggestion #1:
   File: src/data_processor.py
   Issue: Using list comprehension in a loop can be optimized
   Suggestion: Replace with generator expression for memory efficiency

   [y/n] Do you approve this optimization?

Reference Document Support: You can provide reference documentation (like coding standards, architectural guidelines, or best practices documents) to guide the optimization process:

# Use company coding standards
cgr optimize python \
  --reference-document ./docs/coding_standards.md

# Use architectural guidelines
cgr optimize java \
  --reference-document ./ARCHITECTURE.md

# Use performance best practices
cgr optimize rust \
  --reference-document ./docs/performance_guide.md

The agent will incorporate the guidance from your reference documents when suggesting optimizations, ensuring they align with your project's standards and architectural decisions.

Common CLI Arguments:

• --orchestrator: Specify provider:model for main operations (e.g., google:gemini-2.0-flash-thinking-exp-01-21, ollama:llama3.2)
• --cypher: Specify provider:model for graph queries (e.g., google:gemini-2.5-flash-lite-preview-06-17, ollama:codellama)
• --repo-path: Path to repository (defaults to current directory)
• --batch-size: Override Memgraph flush batch size (defaults to MEMGRAPH_BATCH_SIZE in settings)
• --reference-document: Path to reference documentation (optimization only)

Step 5: Dead Code Detection

Once a repository is indexed, report functions and methods that are unreachable from any entry point. The walk starts from roots (exported/public symbols, tests, decorated handlers like routes/tasks/commands, dunder/lifecycle methods) and follows CALLS and REFERENCES edges; anything it never reaches is listed.

# Scan the indexed project (auto-selected when only one exists)
cgr dead-code

# Pick a project when several are indexed
cgr dead-code --project-name my-project

Declare framework/external entry points so the code they reach is not flagged:

cgr dead-code -e main -e cli.run --decorator-root celery_app.task

Exclude generated or vendored code (noisy with library-invoked callbacks):

cgr dead-code --exclude '*client/core*' --exclude '*.gen.*'

Fail CI when new unreachable code appears, writing a JSON report:

cgr dead-code --format json --output dead-code.json --fail-on-found

Results are candidates for review, not a guaranteed delete list: code reached only via dynamic dispatch, reflection, or an external framework may still be reported. See the Dead Code Detection guide for details.

Dead Code CLI Arguments:

• --project-name, -n: Project to scan (defaults to the sole indexed project)
• --entry-point, -e: Treat symbols ending with this qualified name as reachable roots (repeatable)
• --decorator-root: Treat symbols carrying this decorator as roots (repeatable)
• --exclude: Glob matched against a symbol's file path to exclude (repeatable)
• --include-tests / --no-include-tests: Treat test code as roots (on by default)
• --classes / --no-classes: Also report unreachable classes (off by default)
• --format: table (default) or json
• --output, -o: Write the report to a file instead of stdout
• --fail-on-found: Exit with code 1 when any candidate is found