# @autodev/codebase

[![npm version](https://img.shields.io/npm/v/@autodev/codebase)](https://www.npmjs.com/package/@autodev/codebase) [![GitHub stars](https://img.shields.io/github/stars/anrgct/autodev-codebase)](https://github.com/anrgct/autodev-codebase) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A vector embedding-based code semantic search tool with MCP server and multi-model integration. Can be used as a pure CLI tool. Supports Ollama for fully local embedding and reranking, enabling complete offline operation and privacy protection for your code repository. ```sh # Semantic code search - Find code by meaning, not just keywords ╭─ ~/workspace/autodev-codebase ╰─❯ codebase search "user manage" --demo Found 20 results in 5 files for: "user manage" ================================================== File: "hello.js" ================================================== < class UserManager > (L7-20) class UserManager { constructor() { this.users = []; } addUser(user) { this.users.push(user); console.log('User added:', user.name); } getUsers() { return this.users; } } …… # Call graph analysis - Trace function call relationships and execution paths ╭─ ~/workspace/autodev-codebase ╰─❯ codebase call --demo --query="app,addUser" Connections between app, addUser: Found 2 matching node(s): - demo/app:L1-29 - demo/hello.UserManager.addUser:L12-15 Direct connections: - demo/app:L1-29 → demo/hello.UserManager.addUser:L12-15 Chains found: - demo/app:L1-29 → demo/hello.UserManager.addUser:L12-15 # Code outline with AI summaries - Understand code structure at a glance ╭─ ~/workspace/autodev-codebase ╰─❯ codebase outline 'hello.js' --demo --summarize # hello.js (23 lines) └─ Defines a greeting function that logs a personalized hello message and returns a welcome string. Implements a UserManager class managing an array of users with methods to add users and retrieve the current user list. Exports both components for external use. 2--5 | function greetUser └─ Implements user greeting logic by logging a personalized hello message and returning a welcome message 7--20 | class UserManager └─ Manages user data with methods to add users to a list and retrieve all stored users 12--15 | method addUser └─ Adds a user to the users array and logs a confirmation message with the user's name. ``` ## 🚀 Features - **🔍 Semantic Code Search**: Vector-based search using advanced embedding models - **🔗 Call Graph Analysis**: Trace function call relationships and execution paths - **🌐 MCP Server**: HTTP-based MCP server with SSE and stdio adapters - **💻 Pure CLI Tool**: Standalone command-line interface without GUI dependencies - **⚙️ Layered Configuration**: CLI, project, and global config management - **🎯 Advanced Path Filtering**: Glob patterns with brace expansion and exclusions - **🌲 Tree-sitter Parsing**: Support for 40+ programming languages - **💾 Qdrant Integration**: High-performance vector database - **🔄 Multiple Providers**: OpenAI, Ollama, Jina, Gemini, Mistral, OpenRouter, Vercel - **📊 Real-time Watching**: Automatic index updates - **⚡ Batch Processing**: Efficient parallel processing - **📝 Code Outline Extraction**: Generate structured code outlines with AI summaries - **💨 Dependency Analysis Cache**: Intelligent caching for 10-50x faster re-analysis ## 📦 Installation ### 1. Dependencies ```bash brew install ollama ripgrep ollama serve ollama pull nomic-embed-text ``` ### 2. Qdrant ```bash docker run -d -p 6333:6333 -p 6334:6334 --name qdrant qdrant/qdrant ``` ### 3. Install ```bash npm install -g @autodev/codebase codebase config --set embedderProvider=ollama,embedderModelId=nomic-embed-text ``` ## 🛠️ Quick Start ```bash # Demo mode (recommended for first-time) # Creates a demo directory in current working directory for testing # Index & search codebase index --demo codebase search "user greet" --demo # Call graph analysis codebase call --demo --query="app,addUser" # MCP server codebase index --serve --demo ``` ## 📋 Commands ### 📝 Code Outlines ```bash # Extract code structure (functions, classes, methods) codebase outline "src/**/*.ts" # Generate code structure with AI summaries codebase outline "src/**/*.ts" --summarize # View only file-level summaries codebase outline "src/**/*.ts" --summarize --title # Clear summary cache codebase outline --clear-summarize-cache ``` ### 🔗 Call Graph Analysis ```bash # 📊 Statistics Overview (no --query) codebase call # Show statistics overview codebase call --json # JSON format codebase call src/commands # Analyze specific directory # 🔍 Function Query (with --query) codebase call --query="getUser" # Single function call tree (default depth: 3) codebase call --query="main" --depth=5 # Custom depth codebase call --query="getUser,validateUser" # Multi-function connections (default depth: 10) # 🎨 Visualization codebase call --viz graph.json # Export Cytoscape.js format codebase call --open # Open interactive viewer codebase call --viz graph.json --open # Export and open # Specify workspace (works for both modes) codebase call --path=/my/project --query="main" ``` **Query Patterns:** - **Exact match**: `--query="functionName"` or `--query="*ClassName.methodName"` - **Wildcards**: `*` (any characters), `?` (single character) - Examples: `--query="get*"`, `--query="*User*"`, `--query="*.*.get*"` - **Single function**: `--query="main"` - Shows call tree (upward + downward) - Default depth: **3** (avoids excessive output) - **Multiple functions**: `--query="main,helper"` - Analyzes connection paths between functions - Default depth: **10** (deeper search needed for path finding) **Supported Languages:** - **TypeScript/JavaScript** (.ts, .tsx, .js, .jsx) - **Python** (.py) - **Java** (.java) - **C/C++** (.c, .h, .cpp, .cc, .cxx, .hpp, .hxx, .c++) - **C#** (.cs) - **Rust** (.rs) - **Go** (.go) ### 🔍 Indexing & Search ```bash # Index the codebase codebase index --path=/my/project --force # Search with filters codebase search "error handling" --path-filters="src/**/*.ts" # Search with custom limit and minimum score codebase search "authentication" --limit=20 --min-score=0.7 codebase search "API" -l 30 -S 0.5 # Search in JSON format codebase search "authentication" --json # Clear index data codebase index --clear-cache --path=/my/project ``` ### 🌐 MCP Server ```bash # HTTP mode (recommended) codebase index --serve --port=3001 --path=/my/project # Stdio adapter codebase stdio --server-url=http://localhost:3001/mcp ``` ### ⚙️ Configuration ```bash # View config codebase config --get codebase config --get embedderProvider --json # Set config codebase config --set embedderProvider=ollama,embedderModelId=nomic-embed-text codebase config --set --global qdrantUrl=http://localhost:6333 ``` ### 🚀 Advanced Features #### 🔍 LLM-Powered Search Reranking Enable LLM reranking to dramatically improve search relevance: ```bash # Enable reranking with Ollama (recommended) codebase config --set rerankerEnabled=true,rerankerProvider=ollama,rerankerOllamaModelId=qwen3-vl:4b-instruct # Or use OpenAI-compatible providers codebase config --set rerankerEnabled=true,rerankerProvider=openai-compatible,rerankerOpenAiCompatibleModelId=deepseek-chat # Search with automatic reranking codebase search "user authentication" # Results are automatically reranked by LLM ``` **Benefits:** - 🎯 **Higher precision**: LLM understands semantic relevance beyond vector similarity - 📊 **Smart scoring**: Results are reranked on a 0-10 scale based on query relevance - ⚡ **Batch processing**: Efficiently handles large result sets with configurable batch sizes - 🎛️ **Threshold control**: Filter results with `rerankerMinScore` to keep only high-quality matches #### Path Filtering & Export ```bash # Path filtering with brace expansion and exclusions codebase search "API" --path-filters="src/**/*.ts,lib/**/*.js" codebase search "utils" --path-filters="{src,test}/**/*.ts" # Export results in JSON format for scripts codebase search "auth" --json ``` #### Path Filtering & Export ```bash # Path filtering with brace expansion and exclusions codebase search "API" --path-filters="src/**/*.ts,lib/**/*.js" codebase search "utils" --path-filters="{src,test}/**/*.ts" # Export results in JSON format for scripts codebase search "auth" --json ``` ## ⚙️ Configuration ### Config Layers (Priority Order) 1. **CLI Arguments** - Runtime parameters (`--path`, `--config`, `--log-level`, `--force`, etc.) 2. **Project Config** - `./autodev-config.json` (or custom path via `--config`) 3. **Global Config** - `~/.autodev-cache/autodev-config.json` 4. **Built-in Defaults** - Fallback values **Note:** CLI arguments provide runtime override for paths, logging, and operational behavior. For persistent configuration (embedderProvider, API keys, search parameters), use `config --set` to save to config files. ### Common Config Examples **Ollama:** ```json { "embedderProvider": "ollama", "embedderModelId": "nomic-embed-text", "qdrantUrl": "http://localhost:6333" } ``` **OpenAI:** ```json { "embedderProvider": "openai", "embedderModelId": "text-embedding-3-small", "embedderOpenAiApiKey": "sk-your-key", "qdrantUrl": "http://localhost:6333" } ``` **OpenAI-Compatible:** ```json { "embedderProvider": "openai-compatible", "embedderModelId": "text-embedding-3-small", "embedderOpenAiCompatibleApiKey": "sk-your-key", "embedderOpenAiCompatibleBaseUrl": "https://api.openai.com/v1" } ``` ### Key Configuration Options | Category | Options | Description | |----------|---------|-------------| | **Embedding** | `embedderProvider`, `embedderModelId`, `embedderModelDimension` | Provider and model settings | | **API Keys** | `embedderOpenAiApiKey`, `embedderOpenAiCompatibleApiKey` | Authentication | | **Vector Store** | `qdrantUrl`, `qdrantApiKey` | Qdrant connection | | **Search** | `vectorSearchMinScore`, `vectorSearchMaxResults` | Search behavior | | **Reranker** | `rerankerEnabled`, `rerankerProvider` | Result reranking | | **Summarizer** | `summarizerProvider`, `summarizerLanguage`, `summarizerBatchSize` | AI summary generation | **Key CLI Arguments:** - `index` - Index the codebase - `search ` - Search the codebase (required positional argument) - `outline ` - Extract code outlines (supports glob patterns) - `call` - Analyze function call relationships and dependency graphs - `stdio` - Start stdio adapter for MCP - `config` - Manage configuration (use with --get or --set) - `--serve` - Start MCP HTTP server (use with `index` command) - `--summarize` - Generate AI summaries for code outlines - `--dry-run` - Preview operations before execution - `--title` - Show only file-level summaries - `--clear-summarize-cache` - Clear all summary caches - `--path`, `--demo`, `--force` - Common options - `--limit` / `-l ` - Maximum number of search results (default: from config, max 50) - `--min-score` / `-S ` - Minimum similarity score for search results (0-1, default: from config) - `--query ` - Query patterns for call graph analysis (comma-separated) - `--viz ` - Export full dependency data for visualization (cannot use with --query) - `--open` - Open interactive graph viewer - `--depth ` - Set analysis depth for call graphs - `--help` - Show all available options **Configuration Commands:** ```bash # View config codebase config --get codebase config --get --json # Set config (saves to file) codebase config --set embedderProvider=ollama,embedderModelId=nomic-embed-text codebase config --set --global embedderProvider=openai,embedderOpenAiApiKey=sk-xxx # Use custom config file codebase --config=/path/to/config.json config --get codebase --config=/path/to/config.json config --set embedderProvider=ollama # Runtime override (paths, logging, etc.) codebase index --path=/my/project --log-level=info --force ``` For complete configuration reference, see [CONFIG.md](CONFIG.md). ## 🔌 MCP Integration ### HTTP Streamable Mode (Recommended) ```bash codebase index --serve --port=3001 ``` **IDE Config:** ```json { "mcpServers": { "codebase": { "url": "http://localhost:3001/mcp" } } } ``` ### Stdio Adapter ```bash # First start the MCP server in one terminal codebase index --serve --port=3001 # Then connect via stdio adapter in another terminal (for IDEs that require stdio) codebase stdio --server-url=http://localhost:3001/mcp ``` **IDE Config:** ```json { "mcpServers": { "codebase": { "command": "codebase", "args": ["stdio", "--server-url=http://localhost:3001/mcp"] } } } ``` ## 🤝 Contributing Contributions are welcome! Please feel free to submit a Pull Request or open an Issue on [GitHub](https://github.com/anrgct/autodev-codebase). ## 📄 License This project is licensed under the [MIT License](https://opensource.org/licenses/MIT). ## 🙏 Acknowledgments This project is a fork and derivative work based on [Roo Code](https://github.com/RooCodeInc/Roo-Code). We've built upon their excellent foundation to create this specialized codebase analysis tool with enhanced features and MCP server capabilities. ---

**🌟 If you find this tool helpful, please give us a [star on GitHub](https://github.com/anrgct/autodev-codebase)!** Made with ❤️ for the developer community

Autodev Codebase

Install

Autodev Codebase

Install