CodeCompass
About
CodeCompass: AI-powered Vibe Coding with MCP. Connects Git repositories to AI assistants like Claude, using Ollama for privacy or OpenAI for cloud. Integrates with VSCode, Cursor, and more.
Details
- License
- MIT
Explore
- Codebase Analysis: Maps your repository's structure and dependencies, now with support for indexing very large files through automated chunking.
- Smart AI Context with Agentic RAG: Utilizes a sophisticated Retrieval Augmented Generation (RAG) approach. The central agent_query tool intelligently orchestrates internal capabilities to gather comprehensive context. This includes analyzing git diff information (summarized if large), dynamically summarizing extensive file lists or code snippets, and more, ensuring AI suggestions are highly relevant.
- Intelligent Agent Orchestration: The core agent_query tool allows the AI to plan and execute multi-step tasks. It can proactively use a suite of internal capabilities to:
- Search code (capability_searchCodeSnippets)
- Retrieve full file content (capability_getFullFileContent), with summarization for large files.
- List directory contents (capability_listDirectory).
- Fetch adjacent code chunks (capability_getAdjacentFileChunks).
- Analyze repository overviews including diffs and relevant snippets (capability_getRepositoryOverview).
- Request more search results (capability_fetchMoreSearchResults) or more processing time if a query is complex.
- Flexible Setup: Runs locally with Ollama or connects to cloud AI like DeepSeek.
- Highly Configurable: Offers extensive environment variables to fine-tune indexing parameters, agent behavior (like loop steps and refinement iterations), context processing limits, and specific LLM models for tasks like summarization.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
CodeCompassCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
- Node.js v20+ (nodejs.org)
- Docker for Qdrant (docker.com)
- Ollama (ollama.com): For local LLM and embedding capabilities.
- Required models (can be configured via environment variables, see Configuration section):
- Embedding Model: nomic-embed-text:v1.5 (default)
- Suggestion Model (if using Ollama for suggestions): llama3.1:8b (default)
- DeepSeek API Key (optional, for cloud-based suggestions; get from Deepseek)
For Linux and macOS:
You can set an environment variable for the current terminal session using the export command:
export VAR_NAME="value"
For example:
export LLM_PROVIDER="deepseek"
export DEEPSEEK_API_KEY="your_deepseek_api_key_here"
These settings will only last for the current session. To make them permanent, add these
export lines to your shell's configuration file:- For Bash (common default):
~/.bashrc or ~/.bash_profile- For Zsh (common on macOS):
~/.zshrcAfter editing the file, reload it (e.g.,
source ~/.bashrc or source ~/.zshrc) or open a new terminal.
For Windows:
Using Command Prompt (cmd.exe):
set VAR_NAME="value"
For example:
set LLM_PROVIDER="deepseek"
set DEEPSEEK_API_KEY="your_deepseek_api_key_here"
This sets the variable for the current Command Prompt session only.
Using PowerShell:
$Env:VAR_NAME = "value"
For example:
$Env:LLM_PROVIDER = "deepseek"
$Env:DEEPSEEK_API_KEY = "your_deepseek_api_key_here"
This sets the variable for the current PowerShell session only.
To set environment variables permanently on Windows:
1. Search for "environment variables" in the Start Menu.
2. Click on "Edit the system environment variables".
3. In the System Properties window, click the "Environment Variables..." button.
4. You can set User variables (for the current user) or System variables (for all users). Click "New..." under the desired section.
5. Enter the variable name (e.g., LLM_PROVIDER) and value (e.g., deepseek).
6. Click OK on all windows. You may need to restart your Command Prompt, PowerShell, or even your computer for the changes to take full effect.
Alternatively, to set a user environment variable permanently from Command Prompt (requires a new command prompt to see the effect):
setx VAR_NAME "value"
Example:
setx LLM_PROVIDER "deepseek"
setx DEEPSEEK_API_KEY "your_deepseek_api_key_here"
Here's a list of important environment variables. If you choose to use a .env file, you can copy this structure.
```env
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"codecompass": {
"CodeCompass": {
"command": "docker",
"args": [
"run",
"-p",
"6333:6333",
"-p",
"6334:6334",
"qdrant/qdrant"
]
}
}
}
}McpServers
{
"CodeCompass": {
"command": "docker",
"args": [
"run",
"-p",
"6333:6333",
"-p",
"6334:6334",
"qdrant/qdrant"
]
}
}CodeCompass helps developers tackle legacy or existing codebases by giving AI coding assistants the context they need to deliver spot-on suggestions. Legacy code is tough for AI—it’s often messy, outdated, and lacks clear documentation. CodeCompass solves this by analyzing your codebase with Qdrant Vector Store and powering AI with Ollama (local) or cloud agents like DeepSeek, using its Agentic RAG feature to make suggestions smarter and more relevant. It’s like giving your AI a roadmap to your code, so you can vibe code effortlessly.
---
Features
- Codebase Analysis: Maps your repository's structure and dependencies, now with support for indexing very large files through automated chunking.
- Smart AI Context with Agentic RAG: Utilizes a sophisticated Retrieval Augmented Generation (RAG) approach. The central agent_query tool intelligently orchestrates internal capabilities to gather comprehensive context. This includes analyzing git diff information (summarized if large), dynamically summarizing extensive file lists or code snippets, and more, ensuring AI suggestions are highly relevant.
- Intelligent Agent Orchestration: The core agent_query tool allows the AI to plan and execute multi-step tasks. It can proactively use a suite of internal capabilities to:
- Search code (capability_searchCodeSnippets)
- Retrieve full file content (capability_getFullFileContent), with summarization for large files.
- List directory contents (capability_listDirectory).
- Fetch adjacent code chunks (capability_getAdjacentFileChunks).
- Analyze repository overviews including diffs and relevant snippets (capability_getRepositoryOverview).
- Request more search results (capability_fetchMoreSearchResults) or more processing time if a query is complex.
- Flexible Setup: Runs locally with Ollama or connects to cloud AI like DeepSeek.
- Highly Configurable: Offers extensive environment variables to fine-tune indexing parameters, agent behavior (like loop steps and refinement iterations), context processing limits, and specific LLM models for tasks like summarization.
Project Status and Roadmap
Current Status:
CodeCompass has successfully implemented its core features, including:
- Codebase analysis using Qdrant Vector Store.
- Agentic RAG (Retrieval Augmented Generation) for intelligent AI suggestions.
- Flexible integration with local LLMs via Ollama (e.g., llama3.1:8b, nomic-embed-text:v1.5) and cloud-based LLMs like DeepSeek.
The project is actively maintained and considered stable for its current feature set.
Future Enhancements (Under Consideration):
While the core functionality is robust, potential future directions include:
- Support for a broader range of LLM providers (e.g., OpenAI, Gemini, Claude).
- More sophisticated agent capabilities and additional tool integrations.
- Enhanced repository indexing techniques for even more precise context retrieval.
- Streamlined user configuration and an even smoother setup experience.
- Deeper integrations with various IDEs and development workflows.
We welcome community contributions and suggestions for future development! Please see our CONTRIBUTING.md.
Prerequisites
- Node.js v20+ (nodejs.org)
- Docker for Qdrant (docker.com)
- Ollama (ollama.com): For local LLM and embedding capabilities.
- Required models (can be configured via environment variables, see Configuration section):
- Embedding Model: nomic-embed-text:v1.5 (default)
- Suggestion Model (if using Ollama for suggestions): llama3.1:8b (default)
- DeepSeek API Key (optional, for cloud-based suggestions; get from Deepseek)
Installation
1. Install Ollama:
- Linux:
curl -fsSL https://ollama.com/install.sh | sh
- macOS/Windows: Download from ollama.com.
- Ensure the Ollama application is running (or run
ollama serve in your terminal if you installed the CLI version).- Pull the default models (or the models you intend to configure):
ollama pull nomic-embed-text:v1.5 # Default embedding model
ollama pull llama3.1:8b # Default Ollama suggestion model
You can verify installed models with
ollama list.
2. Install Qdrant:
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
Verify at http://localhost:6333/dashboard.
3. Install CodeCompass:
npx -y @alvinveroy/codecompass@latest
This installs CodeCompass globally. You can then run it from any directory.
Usage
CodeCompass can be run in two main modes: as a server (default) or as a client to execute specific tools against a running server.
1. Running the CodeCompass Server:
To start the CodeCompass server, navigate to the root of your git repository and run:
codecompass [repoPath] [--port <number>]
-
[repoPath] (optional): Path to the repository you want CodeCompass to analyze. If omitted, it defaults to the current directory (.).-
--port <number> (optional): Specify the HTTP port for the server. This overrides the HTTP_PORT environment variable and the default port (3001).
Examples:
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
