CodeCompass

What is CodeCompass?

CodeCompass helps developers tackle legacy or existing codebases by giving AI coding assistants the context they need for spot-on suggestions. It analyzes your codebase with Qdrant Vector Store and powers AI using Ollama (local) or cloud agents like DeepSeek, employing Agentic RAG to make suggestions smarter and more relevant. It is designed for developers working with messy, outdated, or poorly documented code who want to use AI-assisted development.

How to use CodeCompass?

Install prerequisites: Node.js v20+, Docker (for Qdrant), Ollama (with nomic-embed-text:v1.5 and optionally llama3.1:8b), and optionally a DeepSeek API key. Run npx -y @alvinveroy/codecompass@latest to install globally. Then start the server with codecompass [repoPath] [--port <number>] from the root of your git repository. You can also use CLI client mode to execute specific tools like agent_query, search_code, or switch_suggestion_model directly.

Key features of CodeCompass

• Maps repository structure and dependencies with large file chunking.
• Agentic RAG intelligently orchestrates context gathering for AI suggestions.
• Central agent_query tool plans multi-step tasks using internal capabilities.
• Supports local LLMs via Ollama or cloud AI like DeepSeek.
• Extensive environment variable configuration for indexing and agent behavior.

Use cases of CodeCompass

• Analyze a large legacy codebase to understand its structure and dependencies.
• Get AI-powered code suggestions for modifying or extending existing code.
• Perform semantic code search across a repository with natural language queries.
• Switch between local and cloud AI models depending on privacy or performance needs.

FAQ from CodeCompass

What are the prerequisites for running CodeCompass?

You need Node.js v20+, Docker (for Qdrant), and Ollama installed. Optionally, a DeepSeek API key is required if you want to use cloud-based suggestions.

How do I set up CodeCompass with a cloud AI provider?

Set the environment variable LLM_PROVIDER to "deepseek" and provide your DEEPSEEK_API_KEY. You can set these in your shell, a .env file, or through your MCP client’s configuration.

How can I switch the suggestion model at runtime?

Use the switch_suggestion_model tool with parameters like {"model": "deepseek-coder", "provider": "deepseek"} via the CLI client or through an MCP client that supports tool calls.

What is the utility HTTP server for?

The utility HTTP server (default port 3001) provides health checks, indexing status, and repository update notifications. If the port is already in use by another CodeCompass instance, the new instance disables its own HTTP server and relays requests to the existing one.

How do I run CodeCompass as a client to execute specific tools?

Use codecompass <tool_name> [json_parameters] [--repo <path>] [--json] [--port <number>]. For example, codecompass search_code '{"query": "database connection setup"}' performs a semantic search and returns results.