[{"_1":2,"_356":-5,"_357":-5},"loaderData",{"_3":4,"_22":23,"_252":253},"root",{"_5":6,"_7":8},"toasts",[],"visitor",{"_9":10,"_11":12},"viewportWidth",1280,"visitorSession",{"_13":14,"_16":17,"_18":-5,"_19":20,"_21":-5},"attributes",[15],"bot","id",21005410,"membership","referenceId","019a17bf-377c-71fd-947e-fd17d1ca8e82","userAccount","routes/_public/mcp/servers/~namespace/~slug/_pages/_layout",{"_24":25,"_26":-5,"_27":28,"_29":40,"_168":169,"_251":151},"availableLocales",[],"githubUser","locale",{"_29":30,"_33":37,"_38":39},"mcpServer",{"_31":32,"_33":34,"_35":36},"description","A high-performance CLI tool that provides semantic code search, advanced architectural analysis, and codebase indexing with vector embeddings across multiple programming languages. Enables AI assistants to understand and navigate large codebases through graph-based relationships and intelligent code pattern detection.","name","CodeGraph CLI MCP Server","readme","# CodeGraph MCP Intelligence Platform\n\n🚀 **Revolutionary AI development intelligence platform with Qwen2.5-Coder-14B-128K integration**\n\n**Transform any MCP-compatible LLM into a codebase expert through semantic intelligence**\n\n[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)\n[![Rust](https://img.shields.io/badge/rust-1.75%2B-orange.svg)](https://www.rust-lang.org/)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)\n[![Qwen](https://img.shields.io/badge/Qwen2.5--Coder-14B--128K-blue.svg)](https://huggingface.co/unsloth/Qwen2.5-Coder-14B-Instruct-128K-GGUF)\n\n## 📋 Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Architecture](#architecture)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [CLI Commands](#cli-commands)\n- [Configuration](#configuration)\n- [User Workflows](#user-workflows)\n- [Integration Guide](#integration-guide)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n## 🎯 Revolutionary Overview\n\nCodeGraph is the **a MCP-based codebase intelligence platform** that transforms any compatible LLM (Claude-4[1m], GPT-5, custom agents) into a codebase expert through advanced semantic analysis enhanced by **Qwen2.5-Coder-14B-128K**.\n\n### 🧠 **Core Innovation: MCP-First Intelligence**\n\n**Architecture**: `Cloud LLMs ↔ MCP Protocol ↔ CodeGraph Server ↔ Qwen2.5-Coder-14B-128K`\n\nAny MCP-compatible AI agent can now:\n- **Understand your specific codebase** like a senior team member\n- **Predict change impacts** before modifications are made\n- **Generate code following your team's exact patterns**\n- **Provide architectural insights** impossible with generic AI\n\n### 🚀 **Revolutionary Capabilities**\n\n- **🧠 Semantic Intelligence**: Qwen2.5-Coder-14B with 128K context for complete codebase understanding\n- **⚡ Single-Pass Edge Processing**: Revolutionary unified AST parsing eliminates double-parsing bottleneck\n- **🎯 AI-Enhanced Symbol Resolution**: 85-90% edge linking success with semantic similarity matching\n- **🗣️ Conversational AI**: Natural language codebase interaction with RAG (Retrieval-Augmented Generation)\n- **💾 Intelligent Caching**: Semantic similarity matching for 50-80% cache hit rates\n- **📊 Pattern Detection**: Analyzes team conventions with advanced ML pipeline\n- **🔗 MCP Protocol**: Works with Claude Code, Codex CLI, Gemini CLI, Crush, Qwen-Code, and any MCP-compatible agent\n\n## 🌍 **Universal Programming Language Support**\n\nCodeGraph provides **revolutionary AI intelligence** across **11 programming languages**, making it the most comprehensive local-first AI development platform available.\n\n### 🚀 **Tier 1: Advanced Semantic Analysis (8 Languages)**\n\n**Complete framework-aware semantic extractors with language-specific intelligence:**\n\n- **🦀 Rust** - Complete ownership/borrowing analysis, trait relationships, async patterns, lifetimes\n- **🐍 Python** - Type hints, docstrings, dynamic analysis, framework detection\n- **⚡ JavaScript** - Modern ES6+, async/await, functional patterns, React/Node.js intelligence\n- **📘 TypeScript** - Type system analysis, generics, interface relationships, Angular/React patterns\n- **🍎 Swift** - iOS/macOS development, SwiftUI patterns, protocol-oriented programming, Combine\n- **🔷 C#** - .NET patterns, LINQ analysis, async/await, dependency injection, Entity Framework\n- **💎 Ruby** - Rails patterns, metaprogramming, dynamic typing, gem analysis\n- **🐘 PHP** - Laravel/Symfony patterns, namespace analysis, modern PHP features, Composer\n\n### 🛠 **Tier 2: Basic Semantic Analysis (3 Languages)**\n\n**Tree-sitter parsing with generic semantic extraction:**\n\n- **🐹 Go** - Goroutines, interfaces, package management, concurrency patterns\n- **☕ Java** - OOP patterns, annotations, Spring framework detection, Maven/Gradle\n- **⚙️ C++** - Modern C++, templates, memory management patterns, CMake\n\n### 🔮 **Future Language Roadmap**\n\n**Note**: The gap between Tier 1 and Tier 2 will be eliminated in future updates. We're actively working on advanced semantic extractors for:\n\n- **Kotlin** (Android/JVM development) - *In progress, version compatibility being resolved*\n- **Dart** (Flutter/mobile development) - *In progress, version compatibility being resolved*\n- **Zig** (Systems programming)\n- **Elixir** (Functional/concurrent programming)\n- **Haskell** (Pure functional programming)\n\n**Adding new languages is now streamlined** - each new language takes approximately 1-4 hours to implement with full semantic analysis.\n\n## 🎯 **Revolutionary MCP Tools (10 Available + 2 AI-Enhanced)**\n\n### **✅ Core Intelligence Tools (Always Available)**\n- **`vector_search`**: Lightning-fast similarity search across 14K+ embedded entities with FAISS optimization\n- **`pattern_detection`**: Advanced team intelligence with 95%+ consistency analysis and ML-powered insights\n- **`graph_neighbors`**: Real dependency relationship exploration with 25K+ edge database\n- **`graph_traverse`**: Architectural flow analysis with multi-hop graph traversal\n- **`performance_metrics`**: Real-time system health monitoring with cache statistics\n\n### **🧠 AI-Powered Analysis Tools (Qwen2.5-Coder-14B-128K)**\n- **`enhanced_search`**: Semantic search + comprehensive AI analysis with 128K context (2-3 seconds)\n- **`semantic_intelligence`**: Deep architectural analysis with complete codebase understanding (4-6 seconds)\n- **`impact_analysis`**: Revolutionary breaking change prediction with dependency cascade analysis (3-5 seconds)\n\n### **🗣️ BREAKTHROUGH: Conversational AI Tools (AI-Enhanced Build)**\n- **`codebase_qa`**: **REVOLUTIONARY** - Natural language Q&A about your codebase with intelligent responses\n - *\"How does authentication work in this system?\"*\n - *\"What would break if I change this function?\"*\n - *\"Explain the data flow from API to database\"*\n- **`code_documentation`**: **REVOLUTIONARY** - AI-powered documentation generation with graph context\n - Analyzes dependencies, usage patterns, and architectural relationships\n - Generates comprehensive docs with source citations and confidence scoring\n\n## ⚡ **Performance Achievements**\n\n### **Existing Performance (Proven)**\n```bash\nParsing: 170K lines in 0.49 seconds (342,852 lines/sec)\nEmbeddings: 21,024 embeddings in 3:24 minutes\nPlatform: M3 Pro 32GB (optimal for Qwen2.5-Coder-14B)\n```\n\n### **BREAKTHROUGH: Revolutionary Performance Achievements**\n```bash\n🌳 Single-Pass Extraction: Nodes + Edges simultaneously (50% speed improvement)\n🔗 Edge Processing: 25,840 relationships with 85%+ resolution success\n💾 Embedding Generation: 14,573 entities with 384-dim ONNX (228 entities/s)\n🧠 AI Symbol Resolution: Semantic similarity matching for unresolved symbols\n🗣️ Conversational AI: Natural language codebase interaction via RAG\n⚡ Processing Speed: 389,801 lines/s | 161.5 files/s | 326,873 edges/s\n📊 Memory Optimization: Auto-scaling batch sizes for 128GB systems\n```\n\n### **Complete AI-Enhanced Stack Performance**\n```bash\n🤖 Qwen2.5-Coder-14B-128K: SOTA code analysis with 128K context window\n📐 ONNX Embeddings: 384-dimensional semantic vectors (optimized for speed)\n🔍 FAISS Vector Search: Sub-second similarity matching across 14K+ entities\n🔗 Graph Database: 25K+ real dependency relationships with RocksDB storage\n🧠 AI Symbol Resolution: Semantic similarity for 85-90% edge linking success\n🗣️ RAG Engine: Conversational AI with hybrid retrieval and streaming responses\n💾 Intelligent Caching: Semantic similarity matching with 90%+ hit rates\n⚡ Zero External Dependencies: 100% local processing with maximum privacy\n```\n\n## 📊 **Performance Benchmarking (M4 Max 128GB)**\n\n### **Production Codebase Results (1,505 files, 2.5M lines)**\n\n```\n🎉 INDEXING COMPLETE - REVOLUTIONARY AI DEVELOPMENT PLATFORM READY!\n┌─────────────────────────────────────────────────────────────────┐\n│ 📊 COMPREHENSIVE INDEXING STATISTICS │\n├─────────────────────────────────────────────────────────────────┤\n│ 📄 Files processed: 1,505 (11 languages supported) │\n│ 📝 Lines analyzed: 2,477,824 (TreeSitter AST parsing) │\n│ 🌳 Semantic nodes: 538,972 (functions: 30,669, classes: 880) │\n│ 🔗 Code relationships: 1,250,000+ extracted (calls, imports) │\n│ 💾 Vector embeddings: 538,972 (384-dim ONNX) │\n│ 🎯 Dependency resolution: 87.3% success (1,091,250+ edges) │\n├─────────────────────────────────────────────────────────────────┤\n│ 🚀 CAPABILITIES UNLOCKED │\n│ ✅ Vector similarity search across 538K+ embedded entities │\n│ ✅ Graph traversal with 1M+ real dependency relationships │\n│ ✅ AI-powered semantic analysis with Qwen2.5-Coder integration │\n│ ✅ Revolutionary edge processing with single-pass extraction │\n│ ✅ Conversational AI: codebase_qa and code_documentation tools │\n└─────────────────────────────────────────────────────────────────┘\n🚀 CodeGraph Universal AI Development Platform: FULLY OPERATIONAL\n```\n\n### **Embedding Provider Performance Comparison**\n\n| Provider | Time | Quality | Use Case |\n|----------|------|---------|----------|\n| **🧠 Ollama nomic-embed-code** | ~15-18h | **SOTA retrieval accuracy** | Production, smaller codebases |\n| **⚡ ONNX all-MiniLM-L6-v2** | **32m 22s** | Good general embeddings | **Large codebases, lunch-break indexing** |\n| **📚 LEANN** | ~4h | Next best thing I could find in Github | No incremental updates |\n\n### **Graph Generation Performance** - the codegraph-rust repository\n\n[00:03:34] [████████████████████████████████████████] 50666/50666 (100%) 🔗 Dependencies resolved: 47486/50666 relationships (93.7% success) | ⚡ 65.5s | 235.9194/s/s | ETA: 0s \n📊 Performance Summary\n┌───────────────────────────────────────────────────────────────────────┐\n│ 📊 COMPREHENSIVE INDEXING STATISTICS │\n├───────────────────────────────────────────────────────────────────────┤\n│ 📄 Files processed: 341 (1 languages supported) │\n│ 📝 Lines analyzed: 185163 (TreeSitter AST parsing) │\n│ 🌳 Semantic nodes: 15087 (functions: 4609, structs: 1222, traits: 55) │\n│ 🔗 Code relationships: 50666 extracted (calls, imports, deps) │\n│ 💾 Vector embeddings: 15087 (384-dim onnx) │\n│ 🎯 Dependency resolution: 93.7% success (47486/50666 edges stored) │\n│───────────────────────────────────────────────────────────────────────│\n\n### **CodeGraph Advantages**\n- ✅ **Incremental Updates**: Can only reprocess changed files (LEANN can't do this)\n- ✅ **Provider Choice**: Speed vs. quality optimization based on needs\n- ✅ **Memory Optimization**: Automatic 128GB M4 Max scaling\n- ✅ **Production Ready**: Index 2.5M lines while having lunch\n- ✅ **Revolutionary MCP**: Any LLM becomes codebase expert\n\n### **REVOLUTIONARY: Recommended Strategy**\n```bash\n# AI-Enhanced Build: Maximum capabilities with conversational AI\n./install-codegraph-osx.sh # Includes ai-enhanced features automatically\n\n# Quick Indexing: Speed-optimized for rapid development\nexport CODEGRAPH_EMBEDDING_PROVIDER=onnx\ncodegraph index . --recursive --languages rust,typescript,python\n\n# Production Quality: Code-specialized embeddings for maximum accuracy\nexport CODEGRAPH_EMBEDDING_PROVIDER=ollama\ncodegraph index . --recursive --force\n\n# AI-Powered Development: Enable conversational codebase interaction\n# Automatically included with ai-enhanced build - no additional setup required\n```\n\n## 🎯 **Success Indicators**\n\n### ✅ **REVOLUTIONARY SUCCESS: Working Correctly When You See:**\n- 🌳 AST parsing extracts thousands of semantic nodes (functions, structs, classes)\n- 🔗 Edge processing achieves 60-90% dependency resolution success\n- 💾 Embedding generation completes with 384-dimensional vectors\n- 🧠 AI symbol resolution improves edge linking via semantic similarity\n- 🗣️ Conversational AI tools respond to natural language queries\n- ⚡ Single-pass extraction eliminates double-parsing bottleneck\n- 📊 Comprehensive completion summary with detailed statistics\n- 🎯 MCP server shows \"Qwen2.5-Coder availability: true\"\n- ✅ Vector search returns real code matches with similarity scores\n\n### 🚨 **Needs Attention When You See:**\n- ❌ \"0 nodes extracted\" → TreeSitter language parser issue\n- ❌ \"0 edges stored\" → Symbol resolution completely failed\n- ❌ Edge processing hangs → Arc unwrap or parsing issues\n- ❌ \"Model not found\" errors → Install required Ollama models\n- ❌ Response times >30 seconds → Memory pressure or model loading\n- ❌ Generic AI responses → Qwen not being used or context not loaded\n- ❌ Build errors about FAISS → Check FAISS library installation\n\n## 📈 **Expected Results**\n\n### **🚀 AI-Enhanced Setup (Recommended)**\n- Installation: 5-10 minutes with `./install-codegraph-osx.sh`\n- Model download: 5-30 minutes (Qwen2.5-Coder-14B-128K + embeddings)\n- Initial indexing: 1-5 minutes with comprehensive AST + edge processing\n- First AI analysis: 10-20 seconds (then cached for millisecond responses)\n\n### **⚡ Daily AI-Powered Development**\n- Incremental indexing: Sub-second updates for changed files\n- Vector search: Instant similarity matching across thousands of entities\n- Edge traversal: Real-time dependency analysis with 25K+ relationships\n- Conversational AI: Natural language codebase interaction via RAG\n- AI symbol resolution: 85-90% dependency linking success\n- Cached responses: Milliseconds for repeated complex queries\n\n## ✨ Features\n\n### 🚀 **Revolutionary Core Features**\n\n- **🌳 Single-Pass AST Processing**\n - **BREAKTHROUGH**: Unified node + edge extraction eliminates double-parsing\n - **11 programming languages** with revolutionary semantic analysis\n - **TreeSitter integration**: Functions, structs, classes, imports with relationships\n - **Edge extraction**: Function calls, imports, dependencies during AST traversal\n - **Performance**: 50% faster than traditional two-phase processing\n\n- **🧠 AI-Enhanced Symbol Resolution**\n - **Multi-pattern matching**: Exact → Simple name → Case variants → AI similarity\n - **Semantic similarity**: 70%+ threshold for intelligent symbol matching\n - **85-90% resolution success**: Maximum dependency graph completeness\n - **Real-time tracking**: Resolution method statistics and performance metrics\n\n- **🗣️ Conversational AI Integration (RAG)**\n - **Natural language Q&A**: Ask complex questions about your codebase\n - **Intelligent documentation**: AI-powered generation with graph context\n - **Hybrid retrieval**: Vector search + Graph traversal + Keyword matching\n - **Source citations**: Precise file/line attribution for transparency\n - **Streaming responses**: Real-time answer generation with progress\n\n- **📊 Comprehensive Intelligence Pipeline**\n - **Vector embeddings**: 384-dimensional ONNX/Ollama with similarity search\n - **Graph database**: 25K+ real dependency relationships with RocksDB\n - **Pattern detection**: Team convention analysis with 95%+ consistency\n - **Performance optimization**: Auto-scaling for 128GB+ systems\n\n## 🏗️ Architecture\n\n```\nCodeGraph System Architecture\n┌─────────────────────────────────────────────────────┐\n│ CLI Interface │\n│ (codegraph CLI) │\n└─────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────┐\n│ Core Engine │\n│ ┌─────────────┐ ┌──────────────┐ ┌────────────┐ │\n│ │ Parser │ │ Graph Store │ │ Vector │ │ \n│ │ (Tree-sittr)│ │ (RocksDB) │ │ Search │ │\n│ └─────────────┘ └──────────────┘ │ (FAISS) │ │\n│ └────────────┘ │\n└─────────────────────────────────────────────────────┘\n │\n ▼\n┌───────────────────────────────────────────────��─────┐\n│ MCP Server Layer │\n│ ┌─────────────┐ ┌──────────────┐ ┌────────────┐ │\n│ │ STDIO │ │ HTTP │ │ Dual │ │\n│ │ Transport │ │ Transport │ │ Mode │ │\n│ └─────────────┘ └──────────────┘ └────────────┘ │\n└─────────────────────────────────────────────────────┘\n```\n\n## 🧠 Embeddings with ONNX Runtime (macOS)\n\n- Default provider: CPU EP. Works immediately with Homebrew `onnxruntime`.\n- Optional CoreML EP: Set `CODEGRAPH_ONNX_EP=coreml` to prefer CoreML when using an ONNX Runtime build that includes CoreML.\n- Fallback: If CoreML EP init fails, CodeGraph logs a warning and falls back to CPU.\n\nHow to use ONNX embeddings\n\n```bash\n# CPU-only (default)\nexport CODEGRAPH_EMBEDDING_PROVIDER=onnx\nexport CODEGRAPH_ONNX_EP=cpu\nexport CODEGRAPH_LOCAL_MODEL=/path/to/onnx-file\n\n# CoreML (requires CoreML-enabled ORT build)\nexport CODEGRAPH_EMBEDDING_PROVIDER=onnx\nexport CODEGRAPH_ONNX_EP=coreml\nexport CODEGRAPH_LOCAL_MODEL=/path/to/onnx-file\n\n\n# Install codegraph\ncargo install --path crates/codegraph-mcp --features \"embeddings,codegraph-vector/onnx,faiss\"\n```\n\nNotes\n\n- ONNX Runtime on Apple platforms accelerates via CoreML, not Metal. If you need GPU acceleration on Apple Silicon, use CoreML where supported.\n- Some models/operators may still run on CPU if CoreML doesn’t support them.\n\nEnabling CoreML feature at build time\n\n- The CoreML registration path is gated by the Cargo feature `onnx-coreml` in `codegraph-vector`.\n- Build with: `cargo build -p codegraph-vector --features \"onnx,onnx-coreml\"`\n- In a full workspace build, enable it via your consuming crate’s features or by adding: `--features codegraph-vector/onnx,codegraph-vector/onnx-coreml`.\n- You still need an ONNX Runtime library that was compiled with CoreML support; the feature only enables the registration call in our code.\n\n## 📦 Prerequisites\n\n### System Requirements\n\n- **Operating System**: Linux, macOS, or Windows\n- **Rust**: 1.75 or higher\n- **Memory**: Minimum 4GB RAM (8GB recommended for large codebases)\n- **Disk Space**: 1GB for installation + space for indexed data\n\n### Required Dependencies\n\n```bash\n# macOS\nbrew install cmake clang\n\n# Ubuntu/Debian\nsudo apt-get update\nsudo apt-get install cmake clang libssl-dev pkg-config\n\n# Fedora/RHEL\nsudo dnf install cmake clang openssl-devel\n```\n\n### Optional Dependencies\n\n- **FAISS** (for vector search acceleration)\n ```bash\n # macOS (required for FAISS feature)\n brew install faiss\n\n # Ubuntu/Debian\n sudo apt-get install libfaiss-dev\n\n # Fedora/RHEL\n sudo dnf install faiss-devel\n ```\n- **Local Embeddings (HuggingFace + Candle + ONNX/ORT(coreML) osx-metal/cuda/cpu)**\n - Enables on-device embedding generation (no external API calls)\n - Downloads models from HuggingFace Hub on first run and caches them locally\n - Internet access required for the initial model download (or pre-populate cache)\n - Default runs on CPU; advanced GPU backends (CUDA/Metal) require appropriate hardware and drivers\n- **CUDA** (for GPU-accelerated embeddings)\n- **Git** (for repository integration)\n\n## 🚀 Performance Benchmarks - pure raw speed!\n\nRun repeatable, end-to-end benchmarks that measure indexing speed (with local embeddings + FAISS), vector search latency, and graph traversal throughput.\n\nFor reference indexing this repository with the example configuration yields the following:\n```bash\n2025-09-19T14:27:46.632335Z INFO codegraph_parser::parser: Parsing completed: 361/361 files, 119401 lines in 0.08s (4485.7 files/s, 1483642 lines/s)\n[00:00:51] [########################################] 14096/14096 Embeddings complete\n```\nApple Macbook Pro M4 Max 128Gb 2025 onnx\n\n### Build with performance features\n\nPick one of the local embedding backends and enable FAISS:\n\n```bash\n# Option A: ONNX Runtime (CoreML on macOS, CPU otherwise)\ncargo install --path crates/codegraph-mcp --features \"embeddings,codegraph-vector/onnx,faiss\"\n\n# Option B: Local HF + Candle (CPU/Metal/CUDA)\ncargo install --path crates/codegraph-mcp --features \"embeddings-local,faiss\"\n```\n\n### Configure local embedding backend\n\nONNX (CoreML/CPU):\n```bash\nbrew install huggingface_hub[cli]\nhf auth login\nhf download Qdrant/all-MiniLM-L6-v2\n# Check download path\n# Best to add these to your shell provider config\nexport CODEGRAPH_EMBEDDING_PROVIDER=onnx\n# macOS: use CoreML\nexport CODEGRAPH_ONNX_EP=coreml # or cpu\nexport CODEGRAPH_LOCAL_MODEL=/path/to/model/(not directly to .onnx)\n```\n\nLocal HF + Candle (CPU/Metal/CUDA):\n\n```bash\nexport CODEGRAPH_EMBEDDING_PROVIDER=local\n# device: cpu | metal | cuda:\nexport CODEGRAPH_LOCAL_MODEL=Qdrant/all-MiniLM-L6-v2\n```\n\n### Run the benchmark\n\n```bash\n# Cold run (cleans .codegraph), warmup queries + timed trials\ncodegraph perf . \\\n --langs rust,ts,go \\\n --warmup 3 --trials 20 \\\n --batch-size 512 --device metal \\\n --clean --format json\n```\n\nWhat it measures\n\n- Indexing: total time to parse -> embed -> build FAISS (global + shards)\n- Embedding throughput: embeddings per second\n- Vector search: latency (avg/p50/p95) across repeated queries\n- Graph traversal: BFS depth=2 micro-benchmark\n\nSample output (numbers will vary by machine and codebase)\n\n```json\n{\n \"env\": {\n \"embedding_provider\": \"local\",\n \"device\": \"metal\",\n \"features\": { \"faiss\": true, \"embeddings\": true }\n },\n \"dataset\": {\n \"path\": \"/repo/large-project\",\n \"languages\": [\"rust\",\"ts\",\"go\"],\n \"files\": 18234,\n \"lines\": 2583190\n },\n \"indexing\": {\n \"total_seconds\": 186.4,\n \"embeddings\": 53421,\n \"throughput_embeddings_per_sec\": 286.6\n },\n \"vector_search\": {\n \"queries\": 100,\n \"latency_ms\": { \"avg\": 18.7, \"p50\": 12.3, \"p95\": 32.9 }\n },\n \"graph\": {\n \"bfs_depth\": 2,\n \"visited_nodes\": 1000,\n \"elapsed_ms\": 41.8\n }\n}\n```\n\nTips for reproducibility\n\n- Use `--clean` for cold start numbers, and run a second time for warm cache numbers.\n- Close background processes that may compete for CPU/GPU.\n- Pin versions: `rustc --version`, FAISS build, and the embedding model.\n- Record the host: CPU/GPU, RAM, storage, OS version.\n\n## 🚀 **Complete Installation Guide**\n\n### **Prerequisites**\n- **Hardware**: 32GB RAM recommended (24GB minimum)\n- **OS**: macOS 11.0+ (or Linux with FAISS support)\n- **Rust**: 1.75+ with Cargo\n- **Ollama**: For local model serving\n\n### **Step 1: Install System Dependencies**\n\n```bash\n# macOS: Install FAISS for vector search\nbrew install faiss\n\n# Verify FAISS installation\nls /opt/homebrew/opt/faiss/lib/\n\n# Install Ollama for local models\ncurl -fsSL https://ollama.com/install.sh | sh\nollama serve &\n```\n\n### **Step 2: Install SOTA Models**\n\n```bash\n# Install Qwen2.5-Coder-14B-128K (SOTA code analysis)\nollama pull hf.co/unsloth/Qwen2.5-Coder-14B-Instruct-128K-GGUF:Q4_K_M\n\n# Install nomic-embed-code (SOTA code embeddings)\nollama pull hf.co/nomic-ai/nomic-embed-code-GGUF:Q4_K_M\n\n# Verify models installed\nollama list | grep -E \"qwen|nomic\"\n```\n\n### **Step 3: Build CodeGraph with Complete Features**\n\n```bash\n# Build with all revolutionary features\nLIBRARY_PATH=\"/opt/homebrew/opt/faiss/lib:$LIBRARY_PATH\" \\\nLD_LIBRARY_PATH=\"/opt/homebrew/opt/faiss/lib:$LD_LIBRARY_PATH\" \\\nMACOSX_DEPLOYMENT_TARGET=11.0 \\\ncargo build --release -p codegraph-mcp \\\n --features \"qwen-integration,faiss,embeddings,embeddings-ollama,codegraph-vector/onnx,ai-enhanced\"\n\n# Verify build\n./target/release/codegraph --version\n```\n\n### **Step 4: Environment Configuration**\n\nSOTA accuracy for small code-bases:\n```bash\n# Configure for complete local stack\nexport CODEGRAPH_MODEL=\"hf.co/unsloth/Qwen2.5-Coder-14B-Instruct-128K-GGUF:Q4_K_M\"\nexport CODEGRAPH_EMBEDDING_PROVIDER=ollama\nexport CODEGRAPH_EMBEDDING_MODEL=nomic-embed-code\nexport RUST_LOG=off\n```\nBlazing speed for large-codebases:\n```bash\n# Configure for complete local stack\nexport CODEGRAPH_MODEL=\"hf.co/unsloth/Qwen2.5-Coder-14B-Instruct-128K-GGUF:Q4_K_M\"\nexport CODEGRAPH_EMBEDDING_PROVIDER=onnx\nexport CODEGRAPH_EMBEDDING_MODEL=path/to/your/embedding_model_onnx_folder\nexport RUST_LOG=off\n```\n---\n\n## 🚀 **Revolutionary Quick Start**\n\n### **Step 1: Initialize Your Project**\n\n```bash\n# Navigate to your codebase\ncd /path/to/your/project\n\n# Initialize CodeGraph (creates .codegraph directory)\n/path/to/codegraph-rust/target/release/codegraph init .\n\n# Expected output:\n# ✓ Created .codegraph/config.toml\n# ✓ Created .codegraph/db/\n# ✓ Created .codegraph/vectors/\n# ✓ Created .codegraph/cache/\n```\n\n### **Step 2: Index Your Codebase (Optimized for Your System)**\n\n```bash\n# Automatic optimization for 128GB M4 Max (recommended)\nLIBRARY_PATH=\"/opt/homebrew/opt/faiss/lib:$LIBRARY_PATH\" \\\nLD_LIBRARY_PATH=\"/opt/homebrew/opt/faiss/lib:$LD_LIBRARY_PATH\" \\\nCODEGRAPH_EMBEDDING_PROVIDER=ollama \\\nCODEGRAPH_EMBEDDING_MODEL=\"hf.co/nomic-ai/nomic-embed-code-GGUF:Q4_K_M\" \\\n./target/release/codegraph index . --recursive --languages typescript,javascript,rust,python\n\n# Expected beautiful output:\n# 🚀 High-memory system detected (128GB) - performance optimized!\n# Workers: 4 → 16 (optimized)\n# Batch size: 100 → 20480 (optimized)\n# 💾 Memory capacity: ~20480 embeddings per batch\n# 📄 Parsing Files | Languages: typescript,javascript,rust,python\n# 💾 🚀 Ultra-High Performance (20K batch) | 95% success rate\n\n# Custom high-performance indexing with large batches\n./target/release/codegraph index . --recursive --batch-size 10240 --languages typescript,javascript\n\n# Maximum performance for 128GB+ systems\n./target/release/codegraph index . --recursive --batch-size 20480 --workers 16 --languages typescript,rust,python,go\n```\n\n### **Performance Expectations (128GB M4 Max)**\n```bash\n✅ Workers: Auto-optimized to 16 (4x parallelism)\n✅ Batch Size: Auto-optimized to 20,480 embeddings\n✅ Processing Speed: 150,000+ lines/second\n✅ Memory Utilization: Optimized for available capacity\n✅ Progress Visualization: Dual bars with success rates\n✅ Beautiful Output: Clean professional experience\n```\n\n### **Step 3: Start Revolutionary MCP Server**\n\n```bash\n# Start MCP server for Claude Desktop/GPT-4 integration\nCODEGRAPH_MODEL=\"hf.co/unsloth/Qwen2.5-Coder-14B-Instruct-128K-GGUF:Q4_K_M\" \\\nRUST_LOG=error \\\n./target/release/codegraph start stdio\n\n# Expected output:\n# ✅ Qwen2.5-Coder-14B-128K available for CodeGraph intelligence\n# ✅ Intelligent response cache initialized\n# MCP server ready for connections\n```\n\n### **Step 4: Configure Claude Desktop**\n\nAdd to your Claude Desktop configuration:\n```json\n{\n \"mcpServers\": {\n \"codegraph\": {\n \"command\": \"/path/to/codegraph-rust/target/release/codegraph\",\n \"args\": [\"start\", \"stdio\"],\n \"cwd\": \"/path/to/your/project\",\n \"env\": {\n \"RUST_LOG\": \"error\",\n \"CODEGRAPH_MODEL\": \"hf.co/unsloth/Qwen2.5-Coder-14B-Instruct-128K-GGUF:Q4_K_M\",\n \"CODEGRAPH_EMBEDDING_PROVIDER\": \"ollama\"\n }\n }\n }\n}\n```\n\n### **Step 5: Experience Revolutionary AI**\n\nRestart Claude Desktop and test:\n```\n\"Analyze the coding patterns and architecture in this codebase\"\n→ Claude gets team intelligence from your semantic analysis\n\n\"What would happen if I modify the authentication system?\"\n→ Claude predicts impact before you make changes\n\n\"Find all GraphQL-related code and explain the patterns\"\n→ Claude uses code-specialized search with perfect relevance\n```\n\n---\n\n## 🚀 **High-Memory System Optimization**\n\n### **128GB M4 Max (Your System) - Ultra-High Performance**\n```bash\n# Automatic optimization (recommended)\n./target/release/codegraph index . --recursive --languages typescript,javascript,rust,python\n\n# Expected optimization:\n# 🚀 High-memory system detected (128GB) - performance optimized!\n# Workers: 4 → 16 (optimized)\n# Batch size: 100 → 20480 (optimized)\n\n# Custom ultra-high performance\n./target/release/codegraph index . --batch-size 20480 --workers 16 --recursive\n\n# Maximum performance testing\n./target/release/codegraph index . --batch-size 40960 --workers 16 --recursive\n```\n\n### **Memory-Based Auto-Optimization**\n```yaml\n128GB+ Systems (M4 Max):\n Workers: 16 (maximum parallelism)\n Batch Size: 20,480 embeddings\n Memory Utilization: Ultra-high performance\n\n64-95GB Systems:\n Workers: 12 (high parallelism)\n Batch Size: 10,240 embeddings\n Memory Utilization: High performance\n\n32-63GB Systems:\n Workers: 8 (medium parallelism)\n Batch Size: 2,048 embeddings\n Memory Utilization: Balanced performance\n\n16-31GB Systems:\n Workers: 6 (conservative)\n Batch Size: 512 embeddings\n Memory Utilization: Memory-conscious\n```\n\n### **Quality of Life Features**\n- **Dual Progress Bars**: Files processed + success rates\n- **Memory Detection**: Automatic system optimization\n- **Beautiful Output**: Unicode progress bars and colored status\n- **Performance Metrics**: Real-time speed, ETA, and success rates\n- **Intelligent Defaults**: Respects user choices while optimizing\n\n---\n\n## 📊 **Embedding Provider Options**\n\n### **Ollama (Recommended - Code-Specialized)**\n```bash\nexport CODEGRAPH_EMBEDDING_PROVIDER=ollama\nexport CODEGRAPH_EMBEDDING_MODEL=\"hf.co/nomic-ai/nomic-embed-code-GGUF:Q4_K_M\"\n\n# Benefits:\n# - Code-specialized understanding (768-dim vectors)\n# - Superior semantic search relevance\n# - Local processing, zero external dependencies\n# - Perfect for your 128GB M4 Max with large batches\n```\n\n### **ONNX (Alternative - Speed Optimized)**\n```bash\nexport CODEGRAPH_EMBEDDING_PROVIDER=onnx\nexport CODEGRAPH_LOCAL_MODEL=sentence-transformers/all-MiniLM-L6-v2\n\n# Benefits:\n# - Faster embedding generation\n# - Lower memory usage\n# - Good general-purpose embeddings\n# - Better for smaller memory systems\n```\n\n### Enabling Local Embeddings (Optional)\n\nIf you want to use a local embedding model (Hugging Face) instead of remote providers:\n\n1) Build with the local embeddings feature for crates that use vector search (the API and/or CLI server):\n! Recommended to use the onnx version for better performance, see the begginning of the README for installation instructions\n\n```bash\n# Build API with local embeddings enabled\ncargo build -p codegraph-api --features codegraph-vector/local-embeddings\n\n# (Optional) If your CLI server crate depends on vector features, enable similarly:\ncargo build -p core-rag-mcp-server --features codegraph-vector/local-embeddings\n```\n\n2) Set environment variables to switch the provider at runtime:\n\n```bash\nexport CODEGRAPH_EMBEDDING_PROVIDER=local\n# Optional: choose a specific HF model (must provide onnx model)\nexport CODEGRAPH_LOCAL_MODEL=path/to/Qdrant/all-MiniLM-L6-v2\n```\n\n3) Run as usual (the first run will download model files from Hugging Face and cache them locally):\n\n```bash\ncargo run -p codegraph-api --features codegraph-vector/local-embeddings\n```\n\nModel cache locations:\n\n- Default Hugging Face cache: `~/.cache/huggingface` (or `$HF_HOME`) via `hf-hub`\n- You can pre-populate this cache to run offline after the first download\n\n```\n\n### Method 2: Install Pre-built Binary\n\n```bash\n# Download the latest release\ncurl -L https://github.com/jakedismo/codegraph-cli-mcp/releases/latest/download/codegraph-$(uname -s)-$(uname -m).tar.gz | tar xz\n\n# Move to PATH\nsudo mv codegraph /usr/local/bin/\n\n# Verify installation\ncodegraph --version\n```\n\n### Method 3: Using Cargo\n\n```bash\n# Install directly from crates.io (when published)\ncargo install codegraph-mcp\n\n# Verify installation\ncodegraph --version\n```\n\n## 🎯 Quick Start\n\n### 1. Initialize a New Project\n\n```bash\n# Initialize CodeGraph in current directory\ncodegraph init\n\n# Initialize with project name\ncodegraph init --name my-project\n```\n\n### 2. Index Your Codebase\n\n```bash\n# Index current directory\ncodegraph index .\n\n# Index with specific languages (expanded support)\ncodegraph index . --languages rust,python,typescript,swift,csharp,ruby,php\n\n# Or with more options in Osx\nRUST_LOG=info,codegraph_vector=debug codegraph index . --workers 10 --batch-size 256 --max-seq-len 512 --force \n\n# Index with file watching\ncodegraph index . --watch\n```\n\n### 3. Start MCP Server\n\n```bash\n# Start with STDIO transport (default)\ncodegraph start stdio\n\n# Start with HTTP transport\ncodegraph start http --port 3000\n\n# Start with dual transport\ncodegraph start dual --port 3000\n\n### (Optional) Start with Local Embeddings\n\n```bash\n# Build with the feature (see installation step above), then:\nexport CODEGRAPH_EMBEDDING_PROVIDER=local\nexport CODEGRAPH_LOCAL_MODEL=Qdrant/all-MiniLM-L6-v2\ncargo run -p codegraph-api --features codegraph-vector/local-embeddings\n```\n\n### 4. Search Your Code\n\n```bash\n# Semantic search\ncodegraph search \"authentication handler\"\n\n# Exact match search\ncodegraph search \"fn authenticate\" --search-type exact\n\n# AST-based search\ncodegraph search \"function with async keyword\" --search-type ast\n```\n\n## 📖 CLI Commands\n\n### Global Options\n\n```bash\ncodegraph [OPTIONS] \n\nOptions:\n -v, --verbose Enable verbose logging\n --config Configuration file path\n -h, --help Print help\n -V, --version Print version\n```\n\n### Command Reference\n\n#### `init` - Initialize CodeGraph Project\n\n```bash\ncodegraph init [OPTIONS] [PATH]\n\nArguments:\n [PATH] Project directory (default: current directory)\n\nOptions:\n --name Project name\n --non-interactive Skip interactive setup\n```\n\n#### `start` - Start MCP Server\n\n```bash\ncodegraph start [OPTIONS]\n\nTransports:\n stdio STDIO transport (default)\n http HTTP streaming transport\n dual Both STDIO and HTTP\n\nOptions:\n --config Server configuration file\n --daemon Run in background\n --pid-file PID file location\n\nHTTP Options:\n -h, --host Host to bind (default: 127.0.0.1)\n -p, --port Port to bind (default: 3000)\n --tls Enable TLS/HTTPS\n --cert TLS certificate file\n --key TLS key file\n --cors Enable CORS\n```\n\n#### `stop` - Stop MCP Server\n\n```bash\ncodegraph stop [OPTIONS]\n\nOptions:\n --pid-file PID file location\n -f, --force Force stop without graceful shutdown\n```\n\n#### `status` - Check Server Status\n\n```bash\ncodegraph status [OPTIONS]\n\nOptions:\n --pid-file PID file location\n -d, --detailed Show detailed status information\n```\n\n#### `index` - Index Project\n\n```bash\ncodegraph index [OPTIONS]\n\nArguments:\n Path to project directory\n\nOptions:\n -l, --languages Languages to index (comma-separated)\n --exclude Exclude patterns (gitignore format)\n --include Include only these patterns\n -r, --recursive Recursively index subdirectories\n --force Force reindex\n --watch Watch for changes\n --workers Number of parallel workers (default: 4)\n```\n\n#### `search` - Search Indexed Code\n\n```bash\ncodegraph search [OPTIONS]\n\nArguments:\n Search query\n\nOptions:\n -t, --search-type Search type (semantic|exact|fuzzy|regex|ast)\n -l, --limit Maximum results (default: 10)\n --threshold Similarity threshold 0.0-1.0 (default: 0.7)\n -f, --format Output format (human|json|yaml|table)\n```\n\n#### `config` - Manage Configuration\n\n```bash\ncodegraph config [OPTIONS]\n\nActions:\n show Show current configuration\n set Set configuration value\n get Get configuration value\n reset Reset to defaults\n validate Validate configuration\n\nOptions:\n --json Output as JSON (for 'show')\n -y, --yes Skip confirmation (for 'reset')\n```\n\n#### `stats` - Show Statistics\n\n```bash\ncodegraph stats [OPTIONS]\n\nOptions:\n --index Show index statistics\n --server Show server statistics\n --performance Show performance metrics\n -f, --format Output format (table|json|yaml|human)\n```\n\n#### `clean` - Clean Resources\n\n```bash\ncodegraph clean [OPTIONS]\n\nOptions:\n --index Clean index database\n --vectors Clean vector embeddings\n --cache Clean cache files\n --all Clean all resources\n -y, --yes Skip confirmation prompt\n```\n\n## ⚙️ Configuration\n\n### Configuration File Structure\n\nCreate a `.codegraph/config.toml` file:\n\n```toml\n# General Configuration\n[general]\nproject_name = \"my-project\"\nversion = \"1.0.0\"\nlog_level = \"info\"\n\n# Indexing Configuration\n[indexing]\nlanguages = [\"rust\", \"python\", \"typescript\", \"javascript\", \"go\", \"swift\", \"csharp\", \"ruby\", \"php\"]\nexclude_patterns = [\"**/node_modules/**\", \"**/target/**\", \"**/.git/**\"]\ninclude_patterns = [\"src/**\", \"lib/**\"]\nrecursive = true\nworkers = 10\nwatch_enabled = false\nincremental = true\n\n# Embedding Configuration\n[embedding]\nmodel = \"local\" # Options: openai, local, custom\ndimension = 1536\nbatch_size = 512\ncache_enabled = true\ncache_size_mb = 500\n\n# Vector Search Configuration\n[vector]\nindex_type = \"flat\" # Options: flat, ivf, hnsw\nnprobe = 10\nsimilarity_metric = \"cosine\" # Options: cosine, euclidean, inner_product\n\n# Database Configuration\n[database]\npath = \"~/.codegraph/db\"\ncache_size_mb = 128\ncompression = true\nwrite_buffer_size_mb = 64\n\n# Server Configuration\n[server]\ndefault_transport = \"stdio\"\nhttp_host = \"127.0.0.1\"\nhttp_port = 3005\nenable_tls = false\ncors_enabled = true\nmax_connections = 100\n\n# Performance Configuration\n[performance]\nmax_file_size_kb = 1024\nparallel_threads = 8\nmemory_limit_mb = 2048\noptimization_level = \"balanced\" # Options: speed, balanced, memory\n```\n\n### Environment Variables\n\n```bash\n# Override configuration with environment variables\nexport CODEGRAPH_LOG_LEVEL=debug\nexport CODEGRAPH_DB_PATH=/custom/path/db\nexport CODEGRAPH_EMBEDDING_MODEL=local\nexport CODEGRAPH_HTTP_PORT=8080\n# Qwen runtime tuning (defaults shown)\nexport CODEGRAPH_QWEN_MAX_TOKENS=1024 # Limit completion length for faster docs\nexport CODEGRAPH_QWEN_TIMEOUT_SECS=180 # Fallback to RAG if Qwen exceeds this (0 disables)\nexport CODEGRAPH_QWEN_CONNECT_TIMEOUT_MS=5000 # Abort if Ollama endpoint cannot be reached quickly\n```\n\n### Embedding Model Configuration\n\n#### OpenAI Embeddings\n\n```toml\n[embedding.openai]\napi_key = \"${OPENAI_API_KEY}\" # Use environment variable\nmodel = \"text-embedding-3-large\"\ndimension = 3072\n```\n\n#### Local Embeddings\n\n```toml\n[embedding.local]\nmodel_path = \"~/.codegraph/models/codestral.gguf\"\ndevice = \"cpu\" # Options: cpu, cuda, metal\ncontext_length = 8192\n```\n\n## 📚 User Workflows\n\n### Workflow 1: Complete Project Setup and Analysis\n\n```bash\n# Step 1: Initialize project\ncodegraph init --name my-awesome-project\n\n# Step 2: Configure settings\ncodegraph config set embedding.model local\ncodegraph config set performance.optimization_level speed\n\n# Step 3: Index the codebase (universal language support)\ncodegraph index . --languages rust,python,swift,csharp,ruby,php --recursive\n\n# Step 4: Start MCP server\ncodegraph start http --port 3000 --daemon\n\n# Step 5: Search and analyze\ncodegraph search \"database connection\" --limit 20\ncodegraph stats --index --performance\n```\n\n### Workflow 2: Continuous Development with Watch Mode\n\n```bash\n# Start indexing with watch mode\ncodegraph index . --watch --workers 8 &\n\n# Start MCP server in dual mode\ncodegraph start dual --daemon\n\n# Monitor changes\ncodegraph status --detailed\n\n# Search while developing\ncodegraph search \"TODO\" --search-type exact\n```\n\n### Workflow 3: Integration with AI Tools\n\n```bash\n# Start MCP server for Claude Desktop or VS Code\ncodegraph start stdio\n\n# Configure for AI assistant integration\ncat > ~/.codegraph/mcp-config.json << EOF\n{\n \"name\": \"codegraph-server\",\n \"version\": \"1.0.0\",\n \"tools\": [\n {\n \"name\": \"analyze_architecture\",\n \"description\": \"Analyze codebase architecture\"\n },\n {\n \"name\": \"find_patterns\",\n \"description\": \"Find code patterns and anti-patterns\"\n }\n ]\n}\nEOF\n```\n\n### Workflow 4: Large Codebase Optimization\n\n```bash\n# Optimize for large codebases\ncodegraph config set performance.memory_limit_mb 8192\ncodegraph config set vector.index_type ivf\ncodegraph config set database.compression true\n\n# Index with optimizations\ncodegraph index /path/to/large/project \\\n --workers 16 \\\n --exclude \"**/test/**,**/vendor/**\"\n\n# Use batch operations\ncodegraph search \"class.*Controller\" --search-type regex --limit 100\n```\n\n## 🔌 Integration Guide\n\n### Integrating with Claude Desktop\n\n1. Add to Claude Desktop configuration:\n\n```json\n{\n \"mcpServers\": {\n \"codegraph\": {\n \"command\": \"codegraph\",\n \"args\": [\"start\", \"stdio\"],\n \"env\": {\n \"CODEGRAPH_CONFIG\": \"~/.codegraph/config.toml\"\n }\n }\n }\n}\n```\n\n2. Restart Claude Desktop to load the MCP server\n\n### Integrating with VS Code\n\n1. Install the MCP extension for VS Code\n2. Add to VS Code settings:\n\n```json\n{\n \"mcp.servers\": {\n \"codegraph\": {\n \"command\": \"codegraph\",\n \"args\": [\"start\", \"stdio\"],\n \"rootPath\": \"${workspaceFolder}\"\n }\n }\n}\n```\n\n### API Integration\n\n```python\nimport requests\nimport json\n\n# Connect to HTTP MCP server\nbase_url = \"http://localhost:3000\"\n\n# Index a project\nresponse = requests.post(f\"{base_url}/index\", json={\n \"path\": \"/path/to/project\",\n \"languages\": [\"python\", \"javascript\"]\n})\n\n# Search code\nresponse = requests.post(f\"{base_url}/search\", json={\n \"query\": \"async function\",\n \"limit\": 10\n})\n\nresults = response.json()\n```\n\n### Using with CI/CD\n\n```yaml\n# GitHub Actions example\nname: CodeGraph Analysis\n\non: [push, pull_request]\n\njobs:\n analyze:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v2\n \n - name: Install CodeGraph\n run: |\n cargo install codegraph-mcp\n \n - name: Index Codebase\n run: |\n codegraph init --non-interactive\n codegraph index . --languages rust,python\n \n - name: Run Analysis\n run: |\n codegraph stats --index --format json > analysis.json\n \n - name: Upload Results\n uses: actions/upload-artifact@v2\n with:\n name: codegraph-analysis\n path: analysis.json\n```\n\n## 🔧 Troubleshooting\n\n### Common Issues and Solutions\n\n#### Issue: Server fails to start\n\n**Solution:**\n\n```bash\n# Check if port is already in use\nlsof -i :3000\n\n# Kill existing process\ncodegraph stop --force\n\n# Start with different port\ncodegraph start http --port 3001\n```\n\n#### Issue: Indexing is slow\n\n**Solution:**\n\n```bash\n# Increase workers\ncodegraph index . --workers 16\n\n# Exclude unnecessary files\ncodegraph index . --exclude \"**/node_modules/**,**/dist/**\"\n\n# Use incremental indexing\ncodegraph config set indexing.incremental true\n```\n\n#### Issue: Out of memory during indexing\n\n**Solution:**\n\n```bash\n# Reduce batch size\ncodegraph config set embedding.batch_size 50\n\n# Limit memory usage\ncodegraph config set performance.memory_limit_mb 1024\n\n# Use streaming mode\ncodegraph index . --streaming\n```\n\n#### Issue: Vector search returns poor results\n\n**Solution:**\n\n```bash\n# Adjust similarity threshold\ncodegraph search \"query\" --threshold 0.5\n\n# Re-index with better embeddings\ncodegraph config set embedding.model openai\ncodegraph index . --force\n\n# Use different search type\ncodegraph search \"query\" --search-type fuzzy\n\n#### Issue: Hugging Face model fails to download\n\n**Solution:**\n```bash\n# Ensure you have internet access and the model name is correct\nexport CODEGRAPH_LOCAL_MODEL=Qdrant/all-MiniLM-L6-v2\n\n# If the model is private, set a HF token (if required by your environment)\nexport HF_TOKEN=your_hf_access_token\n\n# Clear/inspect cache (default): ~/.cache/huggingface\nls -lah ~/.cache/huggingface\n\n# Note: models must include safetensors weights; PyTorch .bin-only models are not supported by the local loader here\n```\n\n#### Issue: Local embeddings are slow\n\n**Solution:**\n\n```bash\n# Reduce batch size via config or environment (CPU defaults prioritize stability)\n# Consider using a smaller model (e.g., all-MiniLM-L6-v2) or enabling GPU backends.\n\n# For Apple Silicon (Metal) or CUDA, additional wiring can be enabled in config.\n# Current default uses CPU; contact maintainers to enable device selectors in your environment.\n```\n\n#### Issue: FAISS linking error during cargo install\n\n**Error:** `ld: library 'faiss_c' not found`\n\n**Solution:**\n\n```bash\n# On macOS: Install FAISS via Homebrew\nbrew install faiss\n\n# Set library paths and retry installation\nexport LIBRARY_PATH=\"/opt/homebrew/opt/faiss/lib:$LIBRARY_PATH\"\nexport LD_LIBRARY_PATH=\"/opt/homebrew/opt/faiss/lib:$LD_LIBRARY_PATH\"\n\n# Retry the cargo install command\ncargo install --path crates/codegraph-mcp --features \"embeddings,codegraph-vector/onnx,faiss\"\n```\n\n**Alternative Solution:**\n\n```bash\n# On Ubuntu/Debian\nsudo apt-get update\nsudo apt-get install libfaiss-dev\n\n# On Fedora/RHEL\nsudo dnf install faiss-devel\n\n# Then retry cargo install\ncargo install --path crates/codegraph-mcp --features \"embeddings,codegraph-vector/onnx,faiss\"\n```\n\n```\n\n### Debug Mode\n\nEnable debug logging for troubleshooting:\n\n```bash\n# Set debug log level\nexport RUST_LOG=debug\ncodegraph --verbose index .\n\n# Check logs\ntail -f ~/.codegraph/logs/codegraph.log\n```\n\n### Health Checks\n\n```bash\n# Check system health\ncodegraph status --detailed\n\n# Validate configuration\ncodegraph config validate\n\n# Test database connection\ncodegraph test db\n\n# Verify embeddings\ncodegraph test embeddings\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/jakedismo/codegraph-cli-mcp.git\ncd codegraph-cli-mcp\n\n# Install development dependencies\ncargo install cargo-watch cargo-nextest\n\n# Run tests\ncargo nextest run\n\n# Run with watch mode\ncargo watch -x check -x test\n```\n\n## 📄 License\n\nThis project is dual-licensed under MIT and Apache 2.0 licenses. See [LICENSE-MIT](LICENSE-MIT) and [LICENSE-APACHE](LICENSE-APACHE) for details.\n\n## 🙏 Acknowledgments\n\n- Built with [Rust](https://www.rust-lang.org/)\n- Powered by [Tree-sitter](https://tree-sitter.github.io/)\n- Vector search by [FAISS](https://github.com/facebookresearch/faiss)\n- Graph storage with [RocksDB](https://rocksdb.org/)\n- MCP Protocol by [Anthropic](https://modelcontextprotocol.io)\n- Ouroboros the ever evolving newer ending agent system\n\n---\n\n

\n Completely built with Ouroboros - The next-generation of coding agent systems\n

\n## ⚙️ Installation (Local)\n\n> **Note:** CodeGraph runs entirely local-first. These steps build the CLI with all AI/Qwen tooling enabled.\n\n### 1. Install dependencies\n\n```bash\n# macOS (Homebrew)\nbrew install faiss\n\n# Rust toolchain\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n```\n\nEnsure `faiss` libs are visible to the linker (the install script sets sensible defaults):\n\n```bash\nexport LIBRARY_PATH=\"/opt/homebrew/opt/faiss/lib:$LIBRARY_PATH\"\nexport LD_LIBRARY_PATH=\"/opt/homebrew/opt/faiss/lib:$LD_LIBRARY_PATH\"\nexport DYLD_LIBRARY_PATH=\"/opt/homebrew/opt/faiss/lib:$DYLD_LIBRARY_PATH\"\n```\n\n### 2. Build + install the CLI\n\nRun the bundled installer from the repo root:\n\n```bash\nbash install-codegraph-osx.sh\n```\n\nThis compiles the release binary with the following features:\n\n```\nai-enhanced, qwen-integration, embeddings,\nfaiss, embeddings-ollama, codegraph-vector/onnx\n```\n\nThe binary is copied to `~/.local/bin/codegraph` (honoring `CODEGRAPH_INSTALL_DIR` if you set it). Make sure that directory is on your `PATH`:\n\n```bash\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n### 3. (Optional) Keep a local copy of the release binary\n\nIf you prefer to run it from the repo, grab the compiled binary and point `CODEGRAPH_BIN` at it:\n\n```bash\ncp target/release/codegraph dist/codegraph\nexport CODEGRAPH_BIN=\"$(pwd)/dist/codegraph\"\n```\n\n### 4. Verify the MCP tools\n\n```bash\nexport NOTIFY_POLLING=true # avoid macOS FSEvents issues\npython3 test_mcp_tools.py # exercises all MCP tools\n```\n\nYou should see the MCP handshake negotiate `protocolVersion: \"2025-06-18\"` and each tool (including `code_documentation`) return structured JSON.\n","English","tag","en-US",{"_41":42,"_13":43,"_49":32,"_50":32,"_16":51,"_52":53,"_33":34,"_72":73,"_80":-5,"_81":-5,"_82":83,"_158":159,"_163":-5,"_60":141,"_164":145,"_63":165,"_166":167},"addedAt","2025-09-15T07:02:35.344505Z",[44,45,46,47,48],"category:code-analysis","category:rag-systems","environment:local","hosting:hybrid","language:rust","descriptionMarkdown","descriptionPlainText",11576,"integrations",[54,65],{"_55":56,"_31":62,"_63":64},"brand",{"_57":58,"_33":59,"_60":61},"logoSvgPath","M12.025 1.13c-5.77 0-10.449 4.647-10.449 10.378 0 1.112.178 2.181.503 3.185.064-.222.203-.444.416-.577a.96.96 0 0 1 .524-.15c.293 0 .584.124.84.284.278.173.48.408.71.694.226.282.458.611.684.951v-.014c.017-.324.106-.622.264-.874s.403-.487.762-.543c.3-.047.596.06.787.203s.31.313.4.467c.15.257.212.468.233.542.01.026.653 1.552 1.657 2.54.616.605 1.01 1.223 1.082 1.912.055.537-.096 1.059-.38 1.572.637.121 1.294.187 1.967.187.657 0 1.298-.063 1.921-.178-.287-.517-.44-1.041-.384-1.581.07-.69.465-1.307 1.081-1.913 1.004-.987 1.647-2.513 1.657-2.539.021-.074.083-.285.233-.542.09-.154.208-.323.4-.467a1.08 1.08 0 0 1 .787-.203c.359.056.604.29.762.543s.247.55.265.874v.015c.225-.34.457-.67.683-.952.23-.286.432-.52.71-.694.257-.16.547-.284.84-.285a.97.97 0 0 1 .524.151c.228.143.373.388.43.625l.006.04a10.3 10.3 0 0 0 .534-3.273c0-5.731-4.678-10.378-10.449-10.378M8.327 6.583a1.5 1.5 0 0 1 .713.174 1.487 1.487 0 0 1 .617 2.013c-.183.343-.762-.214-1.102-.094-.38.134-.532.914-.917.71a1.487 1.487 0 0 1 .69-2.803m7.486 0a1.487 1.487 0 0 1 .689 2.803c-.385.204-.536-.576-.916-.71-.34-.12-.92.437-1.103.094a1.487 1.487 0 0 1 .617-2.013 1.5 1.5 0 0 1 .713-.174m-10.68 1.55a.96.96 0 1 1 0 1.921.96.96 0 0 1 0-1.92m13.838 0a.96.96 0 1 1 0 1.92.96.96 0 0 1 0-1.92M8.489 11.458c.588.01 1.965 1.157 3.572 1.164 1.607-.007 2.984-1.155 3.572-1.164.196-.003.305.12.305.454 0 .886-.424 2.328-1.563 3.202-.22-.756-1.396-1.366-1.63-1.32q-.011.001-.02.006l-.044.026-.01.008-.03.024q-.018.017-.035.036l-.032.04a1 1 0 0 0-.058.09l-.014.025q-.049.088-.11.19a1 1 0 0 1-.083.116 1.2 1.2 0 0 1-.173.18q-.035.029-.075.058a1.3 1.3 0 0 1-.251-.243 1 1 0 0 1-.076-.107c-.124-.193-.177-.363-.337-.444-.034-.016-.104-.008-.2.022q-.094.03-.216.087-.06.028-.125.063l-.13.074q-.067.04-.136.086a3 3 0 0 0-.135.096 3 3 0 0 0-.26.219 2 2 0 0 0-.12.121 2 2 0 0 0-.106.128l-.002.002a2 2 0 0 0-.09.132l-.001.001a1.2 1.2 0 0 0-.105.212q-.013.036-.024.073c-1.139-.875-1.563-2.317-1.563-3.203 0-.334.109-.457.305-.454m.836 10.354c.824-1.19.766-2.082-.365-3.194-1.13-1.112-1.789-2.738-1.789-2.738s-.246-.945-.806-.858-.97 1.499.202 2.362c1.173.864-.233 1.45-.685.64-.45-.812-1.683-2.896-2.322-3.295s-1.089-.175-.938.647 2.822 2.813 2.562 3.244-1.176-.506-1.176-.506-2.866-2.567-3.49-1.898.473 1.23 2.037 2.16c1.564.932 1.686 1.178 1.464 1.53s-3.675-2.511-4-1.297c-.323 1.214 3.524 1.567 3.287 2.405-.238.839-2.71-1.587-3.216-.642-.506.946 3.49 2.056 3.522 2.064 1.29.33 4.568 1.028 5.713-.624m5.349 0c-.824-1.19-.766-2.082.365-3.194 1.13-1.112 1.789-2.738 1.789-2.738s.246-.945.806-.858.97 1.499-.202 2.362c-1.173.864.233 1.45.685.64.451-.812 1.683-2.896 2.322-3.295s1.089-.175.938.647-2.822 2.813-2.562 3.244 1.176-.506 1.176-.506 2.866-2.567 3.49-1.898-.473 1.23-2.037 2.16c-1.564.932-1.686 1.178-1.464 1.53s3.675-2.511 4-1.297c.323 1.214-3.524 1.567-3.287 2.405.238.839 2.71-1.587 3.216-.642.506.946-3.49 2.056-3.522 2.064-1.29.33-4.568 1.028-5.713-.624","Hugging Face","slug","huggingface","Provides integration with Hugging Face Hub for downloading and caching transformer models locally for embedding generation, eliminating the need for external API calls","uid","dhlqhkaw3k",{"_55":66,"_31":70,"_63":71},{"_57":67,"_33":68,"_60":69},"M22.2819 9.8211a5.9847 5.9847 0 0 0-.5157-4.9108 6.0462 6.0462 0 0 0-6.5098-2.9A6.0651 6.0651 0 0 0 4.9807 4.1818a5.9847 5.9847 0 0 0-3.9977 2.9 6.0462 6.0462 0 0 0 .7427 7.0966 5.98 5.98 0 0 0 .511 4.9107 6.051 6.051 0 0 0 6.5146 2.9001A5.9847 5.9847 0 0 0 13.2599 24a6.0557 6.0557 0 0 0 5.7718-4.2058 5.9894 5.9894 0 0 0 3.9977-2.9001 6.0557 6.0557 0 0 0-.7475-7.0729zm-9.022 12.6081a4.4755 4.4755 0 0 1-2.8764-1.0408l.1419-.0804 4.7783-2.7582a.7948.7948 0 0 0 .3927-.6813v-6.7369l2.02 1.1686a.071.071 0 0 1 .038.052v5.5826a4.504 4.504 0 0 1-4.4945 4.4944zm-9.6607-4.1254a4.4708 4.4708 0 0 1-.5346-3.0137l.142.0852 4.783 2.7582a.7712.7712 0 0 0 .7806 0l5.8428-3.3685v2.3324a.0804.0804 0 0 1-.0332.0615L9.74 19.9502a4.4992 4.4992 0 0 1-6.1408-1.6464zM2.3408 7.8956a4.485 4.485 0 0 1 2.3655-1.9728V11.6a.7664.7664 0 0 0 .3879.6765l5.8144 3.3543-2.0201 1.1685a.0757.0757 0 0 1-.071 0l-4.8303-2.7865A4.504 4.504 0 0 1 2.3408 7.872zm16.5963 3.8558L13.1038 8.364 15.1192 7.2a.0757.0757 0 0 1 .071 0l4.8303 2.7913a4.4944 4.4944 0 0 1-.6765 8.1042v-5.6772a.79.79 0 0 0-.407-.667zm2.0107-3.0231l-.142-.0852-4.7735-2.7818a.7759.7759 0 0 0-.7854 0L9.409 9.2297V6.8974a.0662.0662 0 0 1 .0284-.0615l4.8303-2.7866a4.4992 4.4992 0 0 1 6.6802 4.66zM8.3065 12.863l-2.02-1.1638a.0804.0804 0 0 1-.038-.0567V6.0742a4.4992 4.4992 0 0 1 7.3757-3.4537l-.142.0805L8.704 5.459a.7948.7948 0 0 0-.3927.6813zm1.0976-2.3654l2.602-1.4998 2.6069 1.4998v2.9994l-2.5974 1.4997-2.6067-1.4997Z","OpenAI","openai","Supports OpenAI's embedding API for generating vector embeddings of code, enabling semantic search capabilities across indexed codebases","26p9809u9m","namespace",{"_74":75,"_60":79},"owner",{"_76":77},"githubAccount",{"_78":79},"login","Jakedismo","readmeMarkdown","redditPostExternalId","repository",{"_84":85,"_126":127,"_130":131,"_149":-5,"_150":151,"_152":-5,"_153":154},"argumentsJsonSchema",{"_86":87,"_123":124,"_91":125},"properties",{"_88":89,"_93":94,"_96":97,"_99":100,"_102":103,"_105":106,"_108":109,"_111":112,"_114":115,"_117":118,"_120":121},"HF_HOME",{"_31":90,"_91":92},"HuggingFace cache directory","type","string","HF_TOKEN",{"_31":95,"_91":92},"HuggingFace access token for private models","RUST_LOG",{"_31":98,"_91":92},"Rust logging configuration","OPENAI_API_KEY",{"_31":101,"_91":92},"OpenAI API key for embeddings","CODEGRAPH_CONFIG",{"_31":104,"_91":92},"Path to CodeGraph configuration file","CODEGRAPH_DB_PATH",{"_31":107,"_91":92},"Custom path for CodeGraph database","CODEGRAPH_ONNX_EP",{"_31":110,"_91":92},"ONNX Runtime execution provider (cpu, coreml)","CODEGRAPH_HTTP_PORT",{"_31":113,"_91":92},"HTTP port for CodeGraph server","CODEGRAPH_LOG_LEVEL",{"_31":116,"_91":92},"Log level for CodeGraph (debug, info, warn, error)","CODEGRAPH_LOCAL_MODEL",{"_31":119,"_91":92},"Path to local ONNX model file or HuggingFace model name","CODEGRAPH_EMBEDDING_PROVIDER",{"_31":122,"_91":92},"The embedding provider to use (onnx, local, openai, etc.)","required",[],"object","githubProject",{"_35":36,"_128":129},"url","https://github.com/jakedismo/codegraph-rust","githubRepository",{"_132":133,"_134":135,"_136":137,"_16":138,"_139":140,"_33":141,"_74":142,"_144":145,"_146":-5,"_147":148},"defaultBranch","main","fullName","Jakedismo/codegraph-rust","githubTreeId",1891037,26350,"language","Rust","codegraph-rust",{"_78":79,"_63":143},"342r9gjd4c","recentStargazers",0,"spdxLicense","stargazers",5,"glamaJson","inspectable",false,"npmPackage","supportedPlatforms",[155,156,157],"LINUX","MACOS","WINDOWS","scores",{"_160":-5,"_161":-5,"_162":-5},"license","quality","security","simpleIcon","toolCount","f6jx5tt00h","updatedAt","2025-10-06T21:25:37.861548Z","meta",[170,173,175,182,185,187,190,193,196,199,202,204,207,210,212,214,216,218,220],{"_171":172},"title","CodeGraph CLI MCP Server | Glama",{"_174":32,"_33":31},"content",{"_176":177,"_178":179,"_180":181},"href","https://glama.ai/mcp/servers/@Jakedismo/codegraph-rust","rel","canonical","tagName","link",{"_174":34,"_183":184},"property","og:title",{"_174":32,"_183":186},"og:description",{"_174":188,"_183":189},"https://glama.ai/logo.png","og:logo",{"_174":191,"_183":192},"https://glama.ai/mcp/servers/@Jakedismo/codegraph-rust/og-image","og:image",{"_174":194,"_183":195},"630","og:image:height",{"_174":197,"_183":198},"1200","og:image:width",{"_174":200,"_183":201},"website","og:type",{"_174":177,"_183":203},"og:url",{"_174":205,"_183":206},"Glama – MCP Hosting Platform","og:site_name",{"_174":208,"_33":209},"summary_large_image","twitter:card",{"_174":205,"_33":211},"twitter:title",{"_174":32,"_33":213},"twitter:description",{"_174":191,"_33":215},"twitter:image",{"_174":194,"_33":217},"twitter:image:height",{"_174":197,"_33":219},"twitter:image:width",{"_221":222},"script:ld+json",{"_223":224,"_225":226},"@context","http://schema.org","@graph",[227],{"_223":228,"_229":230,"_231":232},"https://schema.org","@type","BreadcrumbList","itemListElement",[233,240,244,248],{"_229":234,"_235":236,"_33":237,"_238":239},"ListItem","item","/","Glama","position",1,{"_229":234,"_235":241,"_33":242,"_238":243},"/mcp","MCP",2,{"_229":234,"_235":245,"_33":246,"_238":247},"/mcp/servers","Servers",3,{"_229":234,"_235":249,"_33":34,"_238":250},"/mcp/servers/@Jakedismo/codegraph-rust",4,"visitorIsMaintainer","routes/_public/mcp/servers/~namespace/~slug/_pages/_explorer/blob/~commit/~/_route",{"_254":255,"_29":261,"_292":293,"_168":307,"_304":331,"_332":333},"blob",{"_174":256,"_257":258,"_259":260},"pub mod loaders;\npub mod resolvers;\npub mod types;\n\n#[cfg(test)]\nmod tests;\n\n#[cfg(feature = \"bench\")]\nmod benchmarks;\n\npub use loaders::*;\npub use resolvers::*;\npub use types::*;\n","fileName","mod.rs","size",180,{"_41":42,"_13":262,"_49":32,"_50":32,"_16":51,"_52":263,"_33":34,"_72":268,"_80":-5,"_81":-5,"_82":271,"_158":291,"_163":-5,"_60":141,"_164":145,"_63":165,"_166":167},[44,45,46,47,48],[264,266],{"_55":265,"_31":62,"_63":64},{"_57":58,"_33":59,"_60":61},{"_55":267,"_31":70,"_63":71},{"_57":67,"_33":68,"_60":69},{"_74":269,"_60":79},{"_76":270},{"_78":79},{"_84":272,"_126":286,"_130":288,"_149":-5,"_150":151,"_152":-5,"_153":290},{"_86":273,"_123":285,"_91":125},{"_88":274,"_93":275,"_96":276,"_99":277,"_102":278,"_105":279,"_108":280,"_111":281,"_114":282,"_117":283,"_120":284},{"_31":90,"_91":92},{"_31":95,"_91":92},{"_31":98,"_91":92},{"_31":101,"_91":92},{"_31":104,"_91":92},{"_31":107,"_91":92},{"_31":110,"_91":92},{"_31":113,"_91":92},{"_31":116,"_91":92},{"_31":119,"_91":92},{"_31":122,"_91":92},[],{"_35":287,"_128":129},"# CodeGraph MCP Intelligence Platform\n\n🚀 **Revolutionary AI development intelligence platform with Qwen2.5-Coder-14B-128K integration**\n\n**Transform any MCP-compatible LLM into a codebase expert through semantic intelligence**\n\n[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)\n[![Rust](https://img.shields.io/badge/rust-1.75%2B-orange.svg)](https://www.rust-lang.org/)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)\n[![Qwen](https://img.shields.io/badge/Qwen2.5--Coder-14B--128K-blue.svg)](https://huggingface.co/unsloth/Qwen2.5-Coder-14B-Instruct-128K-GGUF)\n\n## 📋 Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Architecture](#architecture)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [CLI Commands](#cli-commands)\n- [Configuration](#configuration)\n- [User Workflows](#user-workflows)\n- [Integration Guide](#integration-guide)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n## 🎯 Revolutionary Overview\n\nCodeGraph is the **a MCP-based codebase intelligence platform** that transforms any compatible LLM (Claude-4[1m], GPT-5, custom agents) into a codebase expert through advanced semantic analysis enhanced by **Qwen2.5-Coder-14B-128K**.\n\n### 🧠 **Core Innovation: MCP-First Intelligence**\n\n**Architecture**: `Cloud LLMs ↔ MCP Protocol ↔ CodeGraph Server ↔ Qwen2.5-Coder-14B-128K`\n\nAny MCP-compatible AI agent can now:\n- **Understand your specific codebase** like a senior team member\n- **Predict change impacts** before modifications are made\n- **Generate code following your team's exact patterns**\n- **Provide architectural insights** impossible with generic AI\n\n### 🚀 **Revolutionary Capabilities**\n\n- **🧠 Semantic Intelligence**: Qwen2.5-Coder-14B with 128K context for complete codebase understanding\n- **⚡ Single-Pass Edge Processing**: Revolutionary unified AST parsing eliminates double-parsing bottleneck\n- **🎯 AI-Enhanced Symbol Resolution**: 85-90% edge linking success with semantic similarity matching\n- **🗣️ Conversational AI**: Natural language codebase interaction with RAG (Retrieval-Augmented Generation)\n- **💾 Intelligent Caching**: Semantic similarity matching for 50-80% cache hit rates\n- **📊 Pattern Detection**: Analyzes team conventions with advanced ML pipeline\n- **🔗 MCP Protocol**: Works with Claude Code, Codex CLI, Gemini CLI, Crush, Qwen-Code, and any MCP-compatible agent\n\n## 🌍 **Universal Programming Language Support**\n\nCodeGraph provides **revolutionary AI intelligence** across **11 programming languages**, making it the most comprehensive local-first AI development platform available.\n\n### 🚀 **Tier 1: Advanced Semantic Analysis (8 Languages)**\n\n**Complete framework-aware semantic extractors with language-specific intelligence:**\n\n- **🦀 Rust** - Complete ownership/borrowing analysis, trait relationships, async patterns, lifetimes\n- **🐍 Python** - Type hints, docstrings, dynamic analysis, framework detection\n- **⚡ JavaScript** - Modern ES6+, async/await, functional patterns, React/Node.js intelligence\n- **📘 TypeScript** - Type system analysis, generics, interface relationships, Angular/React patterns\n- **🍎 Swift** - iOS/macOS development, SwiftUI patterns, protocol-oriented programming, Combine\n- **🔷 C#** - .NET patterns, LINQ analysis, async/await, dependency injection, Entity Framework\n- **💎 Ruby** - Rails patterns, metaprogramming, dynamic typing, gem analysis\n- **🐘 PHP** - Laravel/Symfony patterns, namespace analysis, modern PHP features, Composer\n\n### 🛠 **Tier 2: Basic Semantic Analysis (3 Languages)**\n\n**Tree-sitter parsing with generic semantic extraction:**\n\n- **🐹 Go** - Goroutines, interfaces, package management, concurrency patterns\n- **☕ Java** - OOP patterns, annotations, Spring framework detection, Maven/Gradle\n- **⚙️ C++** - Modern C++, templates, memory management patterns, CMake\n\n### 🔮 **Future Language Roadmap**\n\n**Note**: The gap between Tier 1 and Tier 2 will be eliminated in future updates. We're actively working on advanced semantic extractors for:\n\n- **Kotlin** (Android/JVM development) - *In progress, version compatibility being resolved*\n- **Dart** (Flutter/mobile development) - *In progress, version compatibility being resolved*\n- **Zig** (Systems programming)\n- **Elixir** (Functional/concurrent programming)\n- **Haskell** (Pure functional programming)\n\n**Adding new languages is now streamlined** - each new language takes approximately 1-4 hours to implement with full semantic analysis.\n\n## 🎯 **Revolutionary MCP Tools (10 Available + 2 AI-Enhanced)**\n\n### **✅ Core Intelligence Tools (Always Available)**\n- **`vector_search`**: Lightning-fast similarity search across 14K+ embedded entities with FAISS optimization\n- **`pattern_detection`**: Advanced team intelligence with 95%+ consistency analysis and ML-powered insights\n- **`graph_neighbors`**: Real dependency relationship exploration with 25K+ edge database\n- **`graph_traverse`**: Architectural flow analysis with multi-hop graph traversal\n- **`performance_metrics`**: Real-time system health monitoring with cache statistics\n\n### **🧠 AI-Powered Analysis Tools (Qwen2.5-Coder-14B-128K)**\n- **`enhanced_search`**: Semantic search + comprehensive AI analysis with 128K context (2-3 seconds)\n- **`semantic_intelligence`**: Deep architectural analysis with complete codebase understanding (4-6 seconds)\n- **`impact_analysis`**: Revolutionary breaking change prediction with dependency cascade analysis (3-5 seconds)\n\n### **🗣️ BREAKTHROUGH: Conversational AI Tools (AI-Enhanced Build)**\n- **`codebase_qa`**: **REVOLUTIONARY** - Natural language Q&A about your codebase with intelligent responses\n - *\"How does authentication work in this system?\"*\n - *\"What would break if I change this function?\"*\n - *\"Explain the data flow from API to database\"*\n- **`code_documentation`**: **REVOLUTIONARY** - AI-powered documentation generation with graph context\n - Analyzes dependencies, usage patterns, and architectural relationships\n - Generates comprehensive docs with source citations and confidence scoring\n\n## ⚡ **Performance Achievements**\n\n### **Existing Performance (Proven)**\n```bash\nParsing: 170K lines in 0.49 seconds (342,852 lines/sec)\nEmbeddings: 21,024 embeddings in 3:24 minutes\nPlatform: M3 Pro 32GB (optimal for Qwen2.5-Coder-14B)\n```\n\n### **BREAKTHROUGH: Revolutionary Performance Achievements**\n```bash\n🌳 Single-Pass Extraction: Nodes + Edges simultaneously (50% speed improvement)\n🔗 Edge Processing: 25,840 relationships with 85%+ resolution success\n💾 Embedding Generation: 14,573 entities with 384-dim ONNX (228 entities/s)\n🧠 AI Symbol Resolution: Semantic similarity matching for unresolved symbols\n🗣️ Conversational AI: Natural language codebase interaction via RAG\n⚡ Processing Speed: 389,801 lines/s | 161.5 files/s | 326,873 edges/s\n📊 Memory Optimization: Auto-scaling batch sizes for 128GB systems\n```\n\n### **Complete AI-Enhanced Stack Performance**\n```bash\n🤖 Qwen2.5-Coder-14B-128K: SOTA code analysis with 128K context window\n📐 ONNX Embeddings: 384-dimensional semantic vectors (optimized for speed)\n🔍 FAISS Vector Search: Sub-second similarity matching across 14K+ entities\n🔗 Graph Database: 25K+ real dependency relationships with RocksDB storage\n🧠 AI Symbol Resolution: Semantic similarity for 85-90% edge linking success\n🗣️ RAG Engine: Conversational AI with hybrid retrieval and streaming responses\n💾 Intelligent Caching: Semantic similarity matching with 90%+ hit rates\n⚡ Zero External Dependencies: 100% local processing with maximum privacy\n```\n\n## 📊 **Performance Benchmarking (M4 Max 128GB)**\n\n### **Production Codebase Results (1,505 files, 2.5M lines)**\n\n```\n🎉 INDEXING COMPLETE - REVOLUTIONARY AI DEVELOPMENT PLATFORM READY!\n┌─────────────────────────────────────────────────────────────────┐\n│ 📊 COMPREHENSIVE INDEXING STATISTICS │\n├─────────────────────────────────────────────────────────────────┤\n│ 📄 Files processed: 1,505 (11 languages supported) │\n│ 📝 Lines analyzed: 2,477,824 (TreeSitter AST parsing) │\n│ 🌳 Semantic nodes: 538,972 (functions: 30,669, classes: 880) │\n│ 🔗 Code relationships: 1,250,000+ extracted (calls, imports) │\n│ 💾 Vector embeddings: 538,972 (384-dim ONNX) │\n│ 🎯 Dependency resolution: 87.3% success (1,091,250+ edges) │\n├─────────────────────────────────────────────────────────────────┤\n│ 🚀 CAPABILITIES UNLOCKED │\n│ ✅ Vector similarity search across 538K+ embedded entities │\n│ ✅ Graph traversal with 1M+ real dependency relationships │\n│ ✅ AI-powered semantic analysis with Qwen2.5-Coder integration │\n│ ✅ Revolutionary edge processing with single-pass extraction │\n│ ✅ Conversational AI: codebase_qa and code_documentation tools │\n└─────────────────────────────────────────────────────────────────┘\n🚀 CodeGraph Universal AI Development Platform: FULLY OPERATIONAL\n```\n\n### **Embedding Provider Performance Comparison**\n\n| Provider | Time | Quality | Use Case |\n|----------|------|---------|----------|\n| **🧠 Ollama nomic-embed-code** | ~15-18h | **SOTA retrieval accuracy** | Production, smaller codebases |\n| **⚡ ONNX all-MiniLM-L6-v2** | **32m 22s** | Good general embeddings | **Large codebases, lunch-break indexing** |\n| **📚 LEANN** | ~4h | Next best thing I could find in Github | No incremental updates |\n\n### **Graph Generation Performance** - the codegraph-rust repository\n\n[00:03:34] [████████████████████████████████████████] 50666/50666 (100%) 🔗 Dependencies resolved: 47486/50666 relationships (93.7% success) | ⚡ 65.5s | 235.9194/s/s | ETA: 0s \n📊 Performance Summary\n┌───────────────────────────────────────────────────────────────────────┐\n│ 📊 COMPREHENSIVE INDEXING STATISTICS │\n├───────────────────────────────────────────────────────────────────────┤\n│ 📄 Files processed: 341 (1 languages supported) │\n│ 📝 Lines analyzed: 185163 (TreeSitter AST parsing) │\n│ 🌳 Semantic nodes: 15087 (functions: 4609, structs: 1222, traits: 55) │\n│ 🔗 Code relationships: 50666 extracted (calls, imports, deps) │\n│ 💾 Vector embeddings: 15087 (384-dim onnx) │\n│ 🎯 Dependency resolution: 93.7% success (47486/50666 edges stored) │\n│───────────────────────────────────────────────────────────────────────│\n\n### **CodeGraph Advantages**\n- ✅ **Incremental Updates**: Can only reprocess changed files (LEANN can't do this)\n- ✅ **Provider Choice**: Speed vs. quality optimization based on needs\n- ✅ **Memory Optimization**: Automatic 128GB M4 Max scaling\n- ✅ **Production Ready**: Index 2.5M lines while having lunch\n- ✅ **Revolutionary MCP**: Any LLM becomes codebase expert\n\n### **REVOLUTIONARY: Recommended Strategy**\n```bash\n# AI-Enhanced Build: Maximum capabilities with conversational AI\n./install-codegraph-osx.sh # Includes ai-enhanced features automatically\n\n# Quick Indexing: Speed-optimized for rapid development\nexport CODEGRAPH_EMBEDDING_PROVIDER=onnx\ncodegraph index . --recursive --languages rust,typescript,python\n\n# Production Quality: Code-specialized embeddings for maximum accuracy\nexport CODEGRAPH_EMBEDDING_PROVIDER=ollama\ncodegraph index . --recursive --force\n\n# AI-Powered Development: Enable conversational codebase interaction\n# Automatically included with ai-enhanced build - no additional setup required\n```\n\n## 🎯 **Success Indicators**\n\n### ✅ **REVOLUTIONARY SUCCESS: Working Correctly When You See:**\n- 🌳 AST parsing extracts thousands of semantic nodes (functions, structs, classes)\n- 🔗 Edge processing achieves 60-90% dependency resolution success\n- 💾 Embedding generation completes with 384-dimensional vectors\n- 🧠 AI symbol resolution improves edge linking via semantic similarity\n- 🗣️ Conversational AI tools respond to natural language queries\n- ⚡ Single-pass extraction eliminates double-parsing bottleneck\n- 📊 Comprehensive completion summary with detailed statistics\n- 🎯 MCP server shows \"Qwen2.5-Coder availability: true\"\n- ✅ Vector search returns real code matches with similarity scores\n\n### 🚨 **Needs Attention When You See:**\n- ❌ \"0 nodes extracted\" → TreeSitter language parser issue\n- ❌ \"0 edges stored\" → Symbol resolution completely failed\n- ❌ Edge processing hangs → Arc unwrap or parsing issues\n- ❌ \"Model not found\" errors → Install required Ollama models\n- ❌ Response times >30 seconds → Memory pressure or model loading\n- ❌ Generic AI responses → Qwen not being used or context not loaded\n- ❌ Build errors about FAISS → Check FAISS library installation\n\n## 📈 **Expected Results**\n\n### **🚀 AI-Enhanced Setup (Recommended)**\n- Installation: 5-10 minutes with `./install-codegraph-osx.sh`\n- Model download: 5-30 minutes (Qwen2.5-Coder-14B-128K + embeddings)\n- Initial indexing: 1-5 minutes with comprehensive AST + edge processing\n- First AI analysis: 10-20 seconds (then cached for millisecond responses)\n\n### **⚡ Daily AI-Powered Development**\n- Incremental indexing: Sub-second updates for changed files\n- Vector search: Instant similarity matching across thousands of entities\n- Edge traversal: Real-time dependency analysis with 25K+ relationships\n- Conversational AI: Natural language codebase interaction via RAG\n- AI symbol resolution: 85-90% dependency linking success\n- Cached responses: Milliseconds for repeated complex queries\n\n## ✨ Features\n\n### 🚀 **Revolutionary Core Features**\n\n- **🌳 Single-Pass AST Processing**\n - **BREAKTHROUGH**: Unified node + edge extraction eliminates double-parsing\n - **11 programming languages** with revolutionary semantic analysis\n - **TreeSitter integration**: Functions, structs, classes, imports with relationships\n - **Edge extraction**: Function calls, imports, dependencies during AST traversal\n - **Performance**: 50% faster than traditional two-phase processing\n\n- **🧠 AI-Enhanced Symbol Resolution**\n - **Multi-pattern matching**: Exact → Simple name → Case variants → AI similarity\n - **Semantic similarity**: 70%+ threshold for intelligent symbol matching\n - **85-90% resolution success**: Maximum dependency graph completeness\n - **Real-time tracking**: Resolution method statistics and performance metrics\n\n- **🗣️ Conversational AI Integration (RAG)**\n - **Natural language Q&A**: Ask complex questions about your codebase\n - **Intelligent documentation**: AI-powered generation with graph context\n - **Hybrid retrieval**: Vector search + Graph traversal + Keyword matching\n - **Source citations**: Precise file/line attribution for transparency\n - **Streaming responses**: Real-time answer generation with progress\n\n- **📊 Comprehensive Intelligence Pipeline**\n - **Vector embeddings**: 384-dimensional ONNX/Ollama with similarity search\n - **Graph database**: 25K+ real dependency relationships with RocksDB\n - **Pattern detection**: Team convention analysis with 95%+ consistency\n - **Performance optimization**: Auto-scaling for 128GB+ systems\n\n## 🏗️ Architecture\n\n```\nCodeGraph System Architecture\n┌─────────────────────────────────────────────────────┐\n│ CLI Interface │\n│ (codegraph CLI) │\n└─────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────┐\n│ Core Engine │\n│ ┌─────────────┐ ┌──────────────┐ ┌────────────┐ │\n│ │ Parser │ │ Graph Store │ │ Vector │ │ \n│ │ (Tree-sittr)│ │ (RocksDB) │ │ Search │ │\n│ └─────────────┘ └──────────────┘ │ (FAISS) │ │\n│ └────────────┘ │\n└─────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────┐\n│ MCP Server Layer │\n│ ┌─────────────┐ ┌──────────────┐ ┌────────────┐ │\n│ │ STDIO │ │ HTTP │ │ Dual │ │\n│ │ Transport │ │ Transport │ │ Mode │ │\n│ └─────────────┘ └──────────────┘ └────────────┘ │\n└─────────────────────────────────────────────────────┘\n```\n\n## 🧠 Embeddings with ONNX Runtime (macOS)\n\n- Default provider: CPU EP. Works immediately with Homebrew `onnxruntime`.\n- Optional CoreML EP: Set `CODEGRAPH_ONNX_EP=coreml` to prefer CoreML when using an ONNX Runtime build that includes CoreML.\n- Fallback: If CoreML EP init fails, CodeGraph logs a warning and falls back to CPU.\n\nHow to use ONNX embeddings\n\n```bash\n# CPU-only (default)\nexport CODEGRAPH_EMBEDDING_PROVIDER=onnx\nexport CODEGRAPH_ONNX_EP=cpu\nexport CODEGRAPH_LOCAL_MODEL=/path/to/onnx-file\n\n# CoreML (requires CoreML-enabled ORT build)\nexport CODEGRAPH_EMBEDDING_PROVIDER=onnx\nexport CODEGRAPH_ONNX_EP=coreml\nexport CODEGRAPH_LOCAL_MODEL=/path/to/onnx-file\n\n\n# Install codegraph\ncargo install --path crates/codegraph-mcp --features \"embeddings,codegraph-vector/onnx,faiss\"\n```\n\nNotes\n\n- ONNX Runtime on Apple platforms accelerates via CoreML, not Metal. If you need GPU acceleration on Apple Silicon, use CoreML where supported.\n- Some models/operators may still run on CPU if CoreML doesn’t support them.\n\nEnabling CoreML feature at build time\n\n- The CoreML registration path is gated by the Cargo feature `onnx-coreml` in `codegraph-vector`.\n- Build with: `cargo build -p codegraph-vector --features \"onnx,onnx-coreml\"`\n- In a full workspace build, enable it via your consuming crate’s features or by adding: `--features codegraph-vector/onnx,codegraph-vector/onnx-coreml`.\n- You still need an ONNX Runtime library that was compiled with CoreML support; the feature only enables the registration call in our code.\n\n## 📦 Prerequisites\n\n### System Requirements\n\n- **Operating System**: Linux, macOS, or Windows\n- **Rust**: 1.75 or higher\n- **Memory**: Minimum 4GB RAM (8GB recommended for large codebases)\n- **Disk Space**: 1GB for installation + space for indexed data\n\n### Required Dependencies\n\n```bash\n# macOS\nbrew install cmake clang\n\n# Ubuntu/Debian\nsudo apt-get update\nsudo apt-get install cmake clang libssl-dev pkg-config\n\n# Fedora/RHEL\nsudo dnf install cmake clang openssl-devel\n```\n\n### Optional Dependencies\n\n- **FAISS** (for vector search acceleration)\n ```bash\n # macOS (required for FAISS feature)\n brew install faiss\n\n # Ubuntu/Debian\n sudo apt-get install libfaiss-dev\n\n # Fedora/RHEL\n sudo dnf install faiss-devel\n ```\n- **Local Embeddings (HuggingFace + Candle + ONNX/ORT(coreML) osx-metal/cuda/cpu)**\n - Enables on-device embedding generation (no external API calls)\n - Downloads models from HuggingFace Hub on first run and caches them locally\n - Internet access required for the initial model download (or pre-populate cache)\n - Default runs on CPU; advanced GPU backends (CUDA/Metal) require appropriate hardware and drivers\n- **CUDA** (for GPU-accelerated embeddings)\n- **Git** (for repository integration)\n\n## 🚀 Performance Benchmarks - pure raw speed!\n\nRun repeatable, end-to-end benchmarks that measure indexing speed (with local embeddings + FAISS), vector search latency, and graph traversal throughput.\n\nFor reference indexing this repository with the example configuration yields the following:\n```bash\n2025-09-19T14:27:46.632335Z INFO codegraph_parser::parser: Parsing completed: 361/361 files, 119401 lines in 0.08s (4485.7 files/s, 1483642 lines/s)\n[00:00:51] [########################################] 14096/14096 Embeddings complete\n```\nApple Macbook Pro M4 Max 128Gb 2025 onnx\n\n### Build with performance features\n\nPick one of the local embedding backends and enable FAISS:\n\n```bash\n# Option A: ONNX Runtime (CoreML on macOS, CPU otherwise)\ncargo install --path crates/codegraph-mcp --features \"embeddings,codegraph-vector/onnx,faiss\"\n\n# Option B: Local HF + Candle (CPU/Metal/CUDA)\ncargo install --path crates/codegraph-mcp --features \"embeddings-local,faiss\"\n```\n\n### Configure local embedding backend\n\nONNX (CoreML/CPU):\n```bash\nbrew install huggingface_hub[cli]\nhf auth login\nhf download Qdrant/all-MiniLM-L6-v2\n# Check download path\n# Best to add these to your shell provider config\nexport CODEGRAPH_EMBEDDING_PROVIDER=onnx\n# macOS: use CoreML\nexport CODEGRAPH_ONNX_EP=coreml # or cpu\nexport CODEGRAPH_LOCAL_MODEL=/path/to/model/(not directly to .onnx)\n```\n\nLocal HF + Candle (CPU/Metal/CUDA):\n\n```bash\nexport CODEGRAPH_EMBEDDING_PROVIDER=local\n# device: cpu | metal | cuda:\nexport CODEGRAPH_LOCAL_MODEL=Qdrant/all-MiniLM-L6-v2\n```\n\n### Run the benchmark\n\n```bash\n# Cold run (cleans .codegraph), warmup queries + timed trials\ncodegraph perf . \\\n --langs rust,ts,go \\\n --warmup 3 --trials 20 \\\n --batch-size 512 --device metal \\\n --clean --format json\n```\n\nWhat it measures\n\n- Indexing: total time to parse -> embed -> build FAISS (global + shards)\n- Embedding throughput: embeddings per second\n- Vector search: latency (avg/p50/p95) across repeated queries\n- Graph traversal: BFS depth=2 micro-benchmark\n\nSample output (numbers will vary by machine and codebase)\n\n```json\n{\n \"env\": {\n \"embedding_provider\": \"local\",\n \"device\": \"metal\",\n \"features\": { \"faiss\": true, \"embeddings\": true }\n },\n \"dataset\": {\n \"path\": \"/repo/large-project\",\n \"languages\": [\"rust\",\"ts\",\"go\"],\n \"files\": 18234,\n \"lines\": 2583190\n },\n \"indexing\": {\n \"total_seconds\": 186.4,\n \"embeddings\": 53421,\n \"throughput_embeddings_per_sec\": 286.6\n },\n \"vector_search\": {\n \"queries\": 100,\n \"latency_ms\": { \"avg\": 18.7, \"p50\": 12.3, \"p95\": 32.9 }\n },\n \"graph\": {\n \"bfs_depth\": 2,\n \"visited_nodes\": 1000,\n \"elapsed_ms\": 41.8\n }\n}\n```\n\nTips for reproducibility\n\n- Use `--clean` for cold start numbers, and run a second time for warm cache numbers.\n- Close background processes that may compete for CPU/GPU.\n- Pin versions: `rustc --version`, FAISS build, and the embedding model.\n- Record the host: CPU/GPU, RAM, storage, OS version.\n\n## 🚀 **Complete Installation Guide**\n\n### **Prerequisites**\n- **Hardware**: 32GB RAM recommended (24GB minimum)\n- **OS**: macOS 11.0+ (or Linux with FAISS support)\n- **Rust**: 1.75+ with Cargo\n- **Ollama**: For local model serving\n\n### **Step 1: Install System Dependencies**\n\n```bash\n# macOS: Install FAISS for vector search\nbrew install faiss\n\n# Verify FAISS installation\nls /opt/homebrew/opt/faiss/lib/\n\n# Install Ollama for local models\ncurl -fsSL https://ollama.com/install.sh | sh\nollama serve &\n```\n\n### **Step 2: Install SOTA Models**\n\n```bash\n# Install Qwen2.5-Coder-14B-128K (SOTA code analysis)\nollama pull hf.co/unsloth/Qwen2.5-Coder-14B-Instruct-128K-GGUF:Q4_K_M\n\n# Install nomic-embed-code (SOTA code embeddings)\nollama pull hf.co/nomic-ai/nomic-embed-code-GGUF:Q4_K_M\n\n# Verify models installed\nollama list | grep -E \"qwen|nomic\"\n```\n\n### **Step 3: Build CodeGraph with Complete Features**\n\n```bash\n# Build with all revolutionary features\nLIBRARY_PATH=\"/opt/homebrew/opt/faiss/lib:$LIBRARY_PATH\" \\\nLD_LIBRARY_PATH=\"/opt/homebrew/opt/faiss/lib:$LD_LIBRARY_PATH\" \\\nMACOSX_DEPLOYMENT_TARGET=11.0 \\\ncargo build --release -p codegraph-mcp \\\n --features \"qwen-integration,faiss,embeddings,embeddings-ollama,codegraph-vector/onnx,ai-enhanced\"\n\n# Verify build\n./target/release/codegraph --version\n```\n\n### **Step 4: Environment Configuration**\n\nSOTA accuracy for small code-bases:\n```bash\n# Configure for complete local stack\nexport CODEGRAPH_MODEL=\"hf.co/unsloth/Qwen2.5-Coder-14B-Instruct-128K-GGUF:Q4_K_M\"\nexport CODEGRAPH_EMBEDDING_PROVIDER=ollama\nexport CODEGRAPH_EMBEDDING_MODEL=nomic-embed-code\nexport RUST_LOG=off\n```\nBlazing speed for large-codebases:\n```bash\n# Configure for complete local stack\nexport CODEGRAPH_MODEL=\"hf.co/unsloth/Qwen2.5-Coder-14B-Instruct-128K-GGUF:Q4_K_M\"\nexport CODEGRAPH_EMBEDDING_PROVIDER=onnx\nexport CODEGRAPH_EMBEDDING_MODEL=path/to/your/embedding_model_onnx_folder\nexport RUST_LOG=off\n```\n---\n\n## 🚀 **Revolutionary Quick Start**\n\n### **Step 1: Initialize Your Project**\n\n```bash\n# Navigate to your codebase\ncd /path/to/your/project\n\n# Initialize CodeGraph (creates .codegraph directory)\n/path/to/codegraph-rust/target/release/codegraph init .\n\n# Expected output:\n# ✓ Created .codegraph/config.toml\n# ✓ Created .codegraph/db/\n# ✓ Created .codegraph/vectors/\n# ✓ Created .codegraph/cache/\n```\n\n### **Step 2: Index Your Codebase (Optimized for Your System)**\n\n```bash\n# Automatic optimization for 128GB M4 Max (recommended)\nLIBRARY_PATH=\"/opt/homebrew/opt/faiss/lib:$LIBRARY_PATH\" \\\nLD_LIBRARY_PATH=\"/opt/homebrew/opt/faiss/lib:$LD_LIBRARY_PATH\" \\\nCODEGRAPH_EMBEDDING_PROVIDER=ollama \\\nCODEGRAPH_EMBEDDING_MODEL=\"hf.co/nomic-ai/nomic-embed-code-GGUF:Q4_K_M\" \\\n./target/release/codegraph index . --recursive --languages typescript,javascript,rust,python\n\n# Expected beautiful output:\n# 🚀 High-memory system detected (128GB) - performance optimized!\n# Workers: 4 → 16 (optimized)\n# Batch size: 100 → 20480 (optimized)\n# 💾 Memory capacity: ~20480 embeddings per batch\n# 📄 Parsing Files | Languages: typescript,javascript,rust,python\n# 💾 🚀 Ultra-High Performance (20K batch) | 95% success rate\n\n# Custom high-performance indexing with large batches\n./target/release/codegraph index . --recursive --batch-size 10240 --languages typescript,javascript\n\n# Maximum performance for 128GB+ systems\n./target/release/codegraph index . --recursive --batch-size 20480 --workers 16 --languages typescript,rust,python,go\n```\n\n### **Performance Expectations (128GB M4 Max)**\n```bash\n✅ Workers: Auto-optimized to 16 (4x parallelism)\n✅ Batch Size: Auto-optimized to 20,480 embeddings\n✅ Processing Speed: 150,000+ lines/second\n✅ Memory Utilization: Optimized for available capacity\n✅ Progress Visualization: Dual bars with success rates\n✅ Beautiful Output: Clean professional experience\n```\n\n### **Step 3: Start Revolutionary MCP Server**\n\n```bash\n# Start MCP server for Claude Desktop/GPT-4 integration\nCODEGRAPH_MODEL=\"hf.co/unsloth/Qwen2.5-Coder-14B-Instruct-128K-GGUF:Q4_K_M\" \\\nRUST_LOG=error \\\n./target/release/codegraph start stdio\n\n# Expected output:\n# ✅ Qwen2.5-Coder-14B-128K available for CodeGraph intelligence\n# ✅ Intelligent response cache initialized\n# MCP server ready for connections\n```\n\n### **Step 4: Configure Claude Desktop**\n\nAdd to your Claude Desktop configuration:\n```json\n{\n \"mcpServers\": {\n \"codegraph\": {\n \"command\": \"/path/to/codegraph-rust/target/release/codegraph\",\n \"args\": [\"start\", \"stdio\"],\n \"cwd\": \"/path/to/your/project\",\n \"env\": {\n \"RUST_LOG\": \"error\",\n \"CODEGRAPH_MODEL\": \"hf.co/unsloth/Qwen2.5-Coder-14B-Instruct-128K-GGUF:Q4_K_M\",\n \"CODEGRAPH_EMBEDDING_PROVIDER\": \"ollama\"\n }\n }\n }\n}\n```\n\n### **Step 5: Experience Revolutionary AI**\n\nRestart Claude Desktop and test:\n```\n\"Analyze the coding patterns and architecture in this codebase\"\n→ Claude gets team intelligence from your semantic analysis\n\n\"What would happen if I modify the authentication system?\"\n→ Claude predicts impact before you make changes\n\n\"Find all GraphQL-related code and explain the patterns\"\n→ Claude uses code-specialized search with perfect relevance\n```\n\n---\n\n## 🚀 **High-Memory System Optimization**\n\n### **128GB M4 Max (Your System) - Ultra-High Performance**\n```bash\n# Automatic optimization (recommended)\n./target/release/codegraph index . --recursive --languages typescript,javascript,rust,python\n\n# Expected optimization:\n# 🚀 High-memory system detected (128GB) - performance optimized!\n# Workers: 4 → 16 (optimized)\n# Batch size: 100 → 20480 (optimized)\n\n# Custom ultra-high performance\n./target/release/codegraph index . --batch-size 20480 --workers 16 --recursive\n\n# Maximum performance testing\n./target/release/codegraph index . --batch-size 40960 --workers 16 --recursive\n```\n\n### **Memory-Based Auto-Optimization**\n```yaml\n128GB+ Systems (M4 Max):\n Workers: 16 (maximum parallelism)\n Batch Size: 20,480 embeddings\n Memory Utilization: Ultra-high performance\n\n64-95GB Systems:\n Workers: 12 (high parallelism)\n Batch Size: 10,240 embeddings\n Memory Utilization: High performance\n\n32-63GB Systems:\n Workers: 8 (medium parallelism)\n Batch Size: 2,048 embeddings\n Memory Utilization: Balanced performance\n\n16-31GB Systems:\n Workers: 6 (conservative)\n Batch Size: 512 embeddings\n Memory Utilization: Memory-conscious\n```\n\n### **Quality of Life Features**\n- **Dual Progress Bars**: Files processed + success rates\n- **Memory Detection**: Automatic system optimization\n- **Beautiful Output**: Unicode progress bars and colored status\n- **Performance Metrics**: Real-time speed, ETA, and success rates\n- **Intelligent Defaults**: Respects user choices while optimizing\n\n---\n\n## 📊 **Embedding Provider Options**\n\n### **Ollama (Recommended - Code-Specialized)**\n```bash\nexport CODEGRAPH_EMBEDDING_PROVIDER=ollama\nexport CODEGRAPH_EMBEDDING_MODEL=\"hf.co/nomic-ai/nomic-embed-code-GGUF:Q4_K_M\"\n\n# Benefits:\n# - Code-specialized understanding (768-dim vectors)\n# - Superior semantic search relevance\n# - Local processing, zero external dependencies\n# - Perfect for your 128GB M4 Max with large batches\n```\n\n### **ONNX (Alternative - Speed Optimized)**\n```bash\nexport CODEGRAPH_EMBEDDING_PROVIDER=onnx\nexport CODEGRAPH_LOCAL_MODEL=sentence-transformers/all-MiniLM-L6-v2\n\n# Benefits:\n# - Faster embedding generation\n# - Lower memory usage\n# - Good general-purpose embeddings\n# - Better for smaller memory systems\n```\n\n### Enabling Local Embeddings (Optional)\n\nIf you want to use a local embedding model (Hugging Face) instead of remote providers:\n\n1) Build with the local embeddings feature for crates that use vector search (the API and/or CLI server):\n! Recommended to use the onnx version for better performance, see the begginning of the README for installation instructions\n\n```bash\n# Build API with local embeddings enabled\ncargo build -p codegraph-api --features codegraph-vector/local-embeddings\n\n# (Optional) If your CLI server crate depends on vector features, enable similarly:\ncargo build -p core-rag-mcp-server --features codegraph-vector/local-embeddings\n```\n\n2) Set environment variables to switch the provider at runtime:\n\n```bash\nexport CODEGRAPH_EMBEDDING_PROVIDER=local\n# Optional: choose a specific HF model (must provide onnx model)\nexport CODEGRAPH_LOCAL_MODEL=path/to/Qdrant/all-MiniLM-L6-v2\n```\n\n3) Run as usual (the first run will download model files from Hugging Face and cache them locally):\n\n```bash\ncargo run -p codegraph-api --features codegraph-vector/local-embeddings\n```\n\nModel cache locations:\n\n- Default Hugging Face cache: `~/.cache/huggingface` (or `$HF_HOME`) via `hf-hub`\n- You can pre-populate this cache to run offline after the first download\n\n```\n\n### Method 2: Install Pre-built Binary\n\n```bash\n# Download the latest release\ncurl -L https://github.com/jakedismo/codegraph-cli-mcp/releases/latest/download/codegraph-$(uname -s)-$(uname -m).tar.gz | tar xz\n\n# Move to PATH\nsudo mv codegraph /usr/local/bin/\n\n# Verify installation\ncodegraph --version\n```\n\n### Method 3: Using Cargo\n\n```bash\n# Install directly from crates.io (when published)\ncargo install codegraph-mcp\n\n# Verify installation\ncodegraph --version\n```\n\n## 🎯 Quick Start\n\n### 1. Initialize a New Project\n\n```bash\n# Initialize CodeGraph in current directory\ncodegraph init\n\n# Initialize with project name\ncodegraph init --name my-project\n```\n\n### 2. Index Your Codebase\n\n```bash\n# Index current directory\ncodegraph index .\n\n# Index with specific languages (expanded support)\ncodegraph index . --languages rust,python,typescript,swift,csharp,ruby,php\n\n# Or with more options in Osx\nRUST_LOG=info,codegraph_vector=debug codegraph index . --workers 10 --batch-size 256 --max-seq-len 512 --force \n\n# Index with file watching\ncodegraph index . --watch\n```\n\n### 3. Start MCP Server\n\n```bash\n# Start with STDIO transport (default)\ncodegraph start stdio\n\n# Start with HTTP transport\ncodegraph start http --port 3000\n\n# Start with dual transport\ncodegraph start dual --port 3000\n\n### (Optional) Start with Local Embeddings\n\n```bash\n# Build with the feature (see installation step above), then:\nexport CODEGRAPH_EMBEDDING_PROVIDER=local\nexport CODEGRAPH_LOCAL_MODEL=Qdrant/all-MiniLM-L6-v2\ncargo run -p codegraph-api --features codegraph-vector/local-embeddings\n```\n\n### 4. Search Your Code\n\n```bash\n# Semantic search\ncodegraph search \"authentication handler\"\n\n# Exact match search\ncodegraph search \"fn authenticate\" --search-type exact\n\n# AST-based search\ncodegraph search \"function with async keyword\" --search-type ast\n```\n\n## 📖 CLI Commands\n\n### Global Options\n\n```bash\ncodegraph [OPTIONS] \n\nOptions:\n -v, --verbose Enable verbose logging\n --config Configuration file path\n -h, --help Print help\n -V, --version Print version\n```\n\n### Command Reference\n\n#### `init` - Initialize CodeGraph Project\n\n```bash\ncodegraph init [OPTIONS] [PATH]\n\nArguments:\n [PATH] Project directory (default: current directory)\n\nOptions:\n --name Project name\n --non-interactive Skip interactive setup\n```\n\n#### `start` - Start MCP Server\n\n```bash\ncodegraph start [OPTIONS]\n\nTransports:\n stdio STDIO transport (default)\n http HTTP streaming transport\n dual Both STDIO and HTTP\n\nOptions:\n --config Server configuration file\n --daemon Run in background\n --pid-file PID file location\n\nHTTP Options:\n -h, --host Host to bind (default: 127.0.0.1)\n -p, --port Port to bind (default: 3000)\n --tls Enable TLS/HTTPS\n --cert TLS certificate file\n --key TLS key file\n --cors Enable CORS\n```\n\n#### `stop` - Stop MCP Server\n\n```bash\ncodegraph stop [OPTIONS]\n\nOptions:\n --pid-file PID file location\n -f, --force Force stop without graceful shutdown\n```\n\n#### `status` - Check Server Status\n\n```bash\ncodegraph status [OPTIONS]\n\nOptions:\n --pid-file PID file location\n -d, --detailed Show detailed status information\n```\n\n#### `index` - Index Project\n\n```bash\ncodegraph index [OPTIONS]\n\nArguments:\n Path to project directory\n\nOptions:\n -l, --languages Languages to index (comma-separated)\n --exclude Exclude patterns (gitignore format)\n --include Include only these patterns\n -r, --recursive Recursively index subdirectories\n --force Force reindex\n --watch Watch for changes\n --workers Number of parallel workers (default: 4)\n```\n\n#### `search` - Search Indexed Code\n\n```bash\ncodegraph search [OPTIONS]\n\nArguments:\n Search query\n\nOptions:\n -t, --search-type Search type (semantic|exact|fuzzy|regex|ast)\n -l, --limit Maximum results (default: 10)\n --threshold Similarity threshold 0.0-1.0 (default: 0.7)\n -f, --format Output format (human|json|yaml|table)\n```\n\n#### `config` - Manage Configuration\n\n```bash\ncodegraph config [OPTIONS]\n\nActions:\n show Show current configuration\n set Set configuration value\n get Get configuration value\n reset Reset to defaults\n validate Validate configuration\n\nOptions:\n --json Output as JSON (for 'show')\n -y, --yes Skip confirmation (for 'reset')\n```\n\n#### `stats` - Show Statistics\n\n```bash\ncodegraph stats [OPTIONS]\n\nOptions:\n --index Show index statistics\n --server Show server statistics\n --performance Show performance metrics\n -f, --format Output format (table|json|yaml|human)\n```\n\n#### `clean` - Clean Resources\n\n```bash\ncodegraph clean [OPTIONS]\n\nOptions:\n --index Clean index database\n --vectors Clean vector embeddings\n --cache Clean cache files\n --all Clean all resources\n -y, --yes Skip confirmation prompt\n```\n\n## ⚙️ Configuration\n\n### Configuration File Structure\n\nCreate a `.codegraph/config.toml` file:\n\n```toml\n# General Configuration\n[general]\nproject_name = \"my-project\"\nversion = \"1.0.0\"\nlog_level = \"info\"\n\n# Indexing Configuration\n[indexing]\nlanguages = [\"rust\", \"python\", \"typescript\", \"javascript\", \"go\", \"swift\", \"csharp\", \"ruby\", \"php\"]\nexclude_patterns = [\"**/node_modules/**\", \"**/target/**\", \"**/.git/**\"]\ninclude_patterns = [\"src/**\", \"lib/**\"]\nrecursive = true\nworkers = 10\nwatch_enabled = false\nincremental = true\n\n# Embedding Configuration\n[embedding]\nmodel = \"local\" # Options: openai, local, custom\ndimension = 1536\nbatch_size = 512\ncache_enabled = true\ncache_size_mb = 500\n\n# Vector Search Configuration\n[vector]\nindex_type = \"flat\" # Options: flat, ivf, hnsw\nnprobe = 10\nsimilarity_metric = \"cosine\" # Options: cosine, euclidean, inner_product\n\n# Database Configuration\n[database]\npath = \"~/.codegraph/db\"\ncache_size_mb = 128\ncompression = true\nwrite_buffer_size_mb = 64\n\n# Server Configuration\n[server]\ndefault_transport = \"stdio\"\nhttp_host = \"127.0.0.1\"\nhttp_port = 3005\nenable_tls = false\ncors_enabled = true\nmax_connections = 100\n\n# Performance Configuration\n[performance]\nmax_file_size_kb = 1024\nparallel_threads = 8\nmemory_limit_mb = 2048\noptimization_level = \"balanced\" # Options: speed, balanced, memory\n```\n\n### Environment Variables\n\n```bash\n# Override configuration with environment variables\nexport CODEGRAPH_LOG_LEVEL=debug\nexport CODEGRAPH_DB_PATH=/custom/path/db\nexport CODEGRAPH_EMBEDDING_MODEL=local\nexport CODEGRAPH_HTTP_PORT=8080\n# Qwen runtime tuning (defaults shown)\nexport CODEGRAPH_QWEN_MAX_TOKENS=1024 # Limit completion length for faster docs\nexport CODEGRAPH_QWEN_TIMEOUT_SECS=180 # Fallback to RAG if Qwen exceeds this (0 disables)\nexport CODEGRAPH_QWEN_CONNECT_TIMEOUT_MS=5000 # Abort if Ollama endpoint cannot be reached quickly\n```\n\n### Embedding Model Configuration\n\n#### OpenAI Embeddings\n\n```toml\n[embedding.openai]\napi_key = \"${OPENAI_API_KEY}\" # Use environment variable\nmodel = \"text-embedding-3-large\"\ndimension = 3072\n```\n\n#### Local Embeddings\n\n```toml\n[embedding.local]\nmodel_path = \"~/.codegraph/models/codestral.gguf\"\ndevice = \"cpu\" # Options: cpu, cuda, metal\ncontext_length = 8192\n```\n\n## 📚 User Workflows\n\n### Workflow 1: Complete Project Setup and Analysis\n\n```bash\n# Step 1: Initialize project\ncodegraph init --name my-awesome-project\n\n# Step 2: Configure settings\ncodegraph config set embedding.model local\ncodegraph config set performance.optimization_level speed\n\n# Step 3: Index the codebase (universal language support)\ncodegraph index . --languages rust,python,swift,csharp,ruby,php --recursive\n\n# Step 4: Start MCP server\ncodegraph start http --port 3000 --daemon\n\n# Step 5: Search and analyze\ncodegraph search \"database connection\" --limit 20\ncodegraph stats --index --performance\n```\n\n### Workflow 2: Continuous Development with Watch Mode\n\n```bash\n# Start indexing with watch mode\ncodegraph index . --watch --workers 8 &\n\n# Start MCP server in dual mode\ncodegraph start dual --daemon\n\n# Monitor changes\ncodegraph status --detailed\n\n# Search while developing\ncodegraph search \"TODO\" --search-type exact\n```\n\n### Workflow 3: Integration with AI Tools\n\n```bash\n# Start MCP server for Claude Desktop or VS Code\ncodegraph start stdio\n\n# Configure for AI assistant integration\ncat > ~/.codegraph/mcp-config.json << EOF\n{\n \"name\": \"codegraph-server\",\n \"version\": \"1.0.0\",\n \"tools\": [\n {\n \"name\": \"analyze_architecture\",\n \"description\": \"Analyze codebase architecture\"\n },\n {\n \"name\": \"find_patterns\",\n \"description\": \"Find code patterns and anti-patterns\"\n }\n ]\n}\nEOF\n```\n\n### Workflow 4: Large Codebase Optimization\n\n```bash\n# Optimize for large codebases\ncodegraph config set performance.memory_limit_mb 8192\ncodegraph config set vector.index_type ivf\ncodegraph config set database.compression true\n\n# Index with optimizations\ncodegraph index /path/to/large/project \\\n --workers 16 \\\n --exclude \"**/test/**,**/vendor/**\"\n\n# Use batch operations\ncodegraph search \"class.*Controller\" --search-type regex --limit 100\n```\n\n## 🔌 Integration Guide\n\n### Integrating with Claude Desktop\n\n1. Add to Claude Desktop configuration:\n\n```json\n{\n \"mcpServers\": {\n \"codegraph\": {\n \"command\": \"codegraph\",\n \"args\": [\"start\", \"stdio\"],\n \"env\": {\n \"CODEGRAPH_CONFIG\": \"~/.codegraph/config.toml\"\n }\n }\n }\n}\n```\n\n2. Restart Claude Desktop to load the MCP server\n\n### Integrating with VS Code\n\n1. Install the MCP extension for VS Code\n2. Add to VS Code settings:\n\n```json\n{\n \"mcp.servers\": {\n \"codegraph\": {\n \"command\": \"codegraph\",\n \"args\": [\"start\", \"stdio\"],\n \"rootPath\": \"${workspaceFolder}\"\n }\n }\n}\n```\n\n### API Integration\n\n```python\nimport requests\nimport json\n\n# Connect to HTTP MCP server\nbase_url = \"http://localhost:3000\"\n\n# Index a project\nresponse = requests.post(f\"{base_url}/index\", json={\n \"path\": \"/path/to/project\",\n \"languages\": [\"python\", \"javascript\"]\n})\n\n# Search code\nresponse = requests.post(f\"{base_url}/search\", json={\n \"query\": \"async function\",\n \"limit\": 10\n})\n\nresults = response.json()\n```\n\n### Using with CI/CD\n\n```yaml\n# GitHub Actions example\nname: CodeGraph Analysis\n\non: [push, pull_request]\n\njobs:\n analyze:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v2\n \n - name: Install CodeGraph\n run: |\n cargo install codegraph-mcp\n \n - name: Index Codebase\n run: |\n codegraph init --non-interactive\n codegraph index . --languages rust,python\n \n - name: Run Analysis\n run: |\n codegraph stats --index --format json > analysis.json\n \n - name: Upload Results\n uses: actions/upload-artifact@v2\n with:\n name: codegraph-analysis\n path: analysis.json\n```\n\n## 🔧 Troubleshooting\n\n### Common Issues and Solutions\n\n#### Issue: Server fails to start\n\n**Solution:**\n\n```bash\n# Check if port is already in use\nlsof -i :3000\n\n# Kill existing process\ncodegraph stop --force\n\n# Start with different port\ncodegraph start http --port 3001\n```\n\n#### Issue: Indexing is slow\n\n**Solution:**\n\n```bash\n# Increase workers\ncodegraph index . --workers 16\n\n# Exclude unnecessary files\ncodegraph index . --exclude \"**/node_modules/**,**/dist/**\"\n\n# Use incremental indexing\ncodegraph config set indexing.incremental true\n```\n\n#### Issue: Out of memory during indexing\n\n**Solution:**\n\n```bash\n# Reduce batch size\ncodegraph config set embedding.batch_size 50\n\n# Limit memory usage\ncodegraph config set performance.memory_limit_mb 1024\n\n# Use streaming mode\ncodegraph index . --streaming\n```\n\n#### Issue: Vector search returns poor results\n\n**Solution:**\n\n```bash\n# Adjust similarity threshold\ncodegraph search \"query\" --threshold 0.5\n\n# Re-index with better embeddings\ncodegraph config set embedding.model openai\ncodegraph index . --force\n\n# Use different search type\ncodegraph search \"query\" --search-type fuzzy\n\n#### Issue: Hugging Face model fails to download\n\n**Solution:**\n```bash\n# Ensure you have internet access and the model name is correct\nexport CODEGRAPH_LOCAL_MODEL=Qdrant/all-MiniLM-L6-v2\n\n# If the model is private, set a HF token (if required by your environment)\nexport HF_TOKEN=your_hf_access_token\n\n# Clear/inspect cache (default): ~/.cache/huggingface\nls -lah ~/.cache/huggingface\n\n# Note: models must include safetensors weights; PyTorch .bin-only models are not supported by the local loader here\n```\n\n#### Issue: Local embeddings are slow\n\n**Solution:**\n\n```bash\n# Reduce batch size via config or environment (CPU defaults prioritize stability)\n# Consider using a smaller model (e.g., all-MiniLM-L6-v2) or enabling GPU backends.\n\n# For Apple Silicon (Metal) or CUDA, additional wiring can be enabled in config.\n# Current default uses CPU; contact maintainers to enable device selectors in your environment.\n```\n\n#### Issue: FAISS linking error during cargo install\n\n**Error:** `ld: library 'faiss_c' not found`\n\n**Solution:**\n\n```bash\n# On macOS: Install FAISS via Homebrew\nbrew install faiss\n\n# Set library paths and retry installation\nexport LIBRARY_PATH=\"/opt/homebrew/opt/faiss/lib:$LIBRARY_PATH\"\nexport LD_LIBRARY_PATH=\"/opt/homebrew/opt/faiss/lib:$LD_LIBRARY_PATH\"\n\n# Retry the cargo install command\ncargo install --path crates/codegraph-mcp --features \"embeddings,codegraph-vector/onnx,faiss\"\n```\n\n**Alternative Solution:**\n\n```bash\n# On Ubuntu/Debian\nsudo apt-get update\nsudo apt-get install libfaiss-dev\n\n# On Fedora/RHEL\nsudo dnf install faiss-devel\n\n# Then retry cargo install\ncargo install --path crates/codegraph-mcp --features \"embeddings,codegraph-vector/onnx,faiss\"\n```\n\n```\n\n### Debug Mode\n\nEnable debug logging for troubleshooting:\n\n```bash\n# Set debug log level\nexport RUST_LOG=debug\ncodegraph --verbose index .\n\n# Check logs\ntail -f ~/.codegraph/logs/codegraph.log\n```\n\n### Health Checks\n\n```bash\n# Check system health\ncodegraph status --detailed\n\n# Validate configuration\ncodegraph config validate\n\n# Test database connection\ncodegraph test db\n\n# Verify embeddings\ncodegraph test embeddings\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/jakedismo/codegraph-cli-mcp.git\ncd codegraph-cli-mcp\n\n# Install development dependencies\ncargo install cargo-watch cargo-nextest\n\n# Run tests\ncargo nextest run\n\n# Run with watch mode\ncargo watch -x check -x test\n```\n\n## 📄 License\n\nThis project is dual-licensed under MIT and Apache 2.0 licenses. See [LICENSE-MIT](LICENSE-MIT) and [LICENSE-APACHE](LICENSE-APACHE) for details.\n\n## 🙏 Acknowledgments\n\n- Built with [Rust](https://www.rust-lang.org/)\n- Powered by [Tree-sitter](https://tree-sitter.github.io/)\n- Vector search by [FAISS](https://github.com/facebookresearch/faiss)\n- Graph storage with [RocksDB](https://rocksdb.org/)\n- MCP Protocol by [Anthropic](https://modelcontextprotocol.io)\n- Ouroboros the ever evolving newer ending agent system\n\n---\n\n

\n Completely built with Ouroboros - The next-generation of coding agent systems\n

MCP directory API