CodeCompass

CodeCompass

CodeCompass は、AI コーディングアシスタントに的確な提案に必要なコンテキストを提供し、開発者がレガシーコードや既存のコードベースに取り組むのを支援します。レガシーコードは、雑然としていたり、古くなっていたり、明確なドキュメントがなかったりすることが多く、AI にとって扱いが難しいものです。CodeCompass は、Qdrant Vector Store でコードベースを分析し、Ollama（ローカル）や DeepSeek などのクラウドエージェントを活用して AI の能力を高めます。さらに、Agentic RAG 機能により、提案をよりスマートで関連性の高いものにします。AI にコードの道しるべを与えるようなもので、気軽にバイブコーディングを楽しめます。

---

機能

• コードベース分析：リポジトリの構造と依存関係をマッピングします。自動チャンク分割により、非常に大きなファイルのインデックス作成にも対応しました。
• Agentic RAG によるスマートな AI コンテキスト：高度な Retrieval Augmented Generation（RAG）アプローチを活用します。中核となる agent_query ツールが内部機能をインテリジェントに連携させ、包括的なコンテキストを収集します。これには、git diff 情報の分析（大規模な場合は要約）、大量のファイルリストやコードスニペットの動的な要約などが含まれ、AI の提案が高い関連性を保てるようにします。
• インテリジェントなエージェントオーケストレーション：中核となる agent_query ツールにより、AI は複数のステップから成るタスクを計画して実行できます。次のような内部機能を積極的に活用できます。
  • コードを検索する（capability_searchCodeSnippets）
  • ファイルの全内容を取得する（capability_getFullFileContent）。大きなファイルは要約されます。
  • ディレクトリの内容を一覧表示する（capability_listDirectory）。
  • 隣接するコードチャンクを取得する（capability_getAdjacentFileChunks）。
  • 差分や関連するスニペットを含むリポジトリの概要を分析する（capability_getRepositoryOverview）。
  • 検索結果をさらに取得する（capability_fetchMoreSearchResults）、またはクエリが複雑な場合に処理時間を延長する。
• 柔軟なセットアップ：Ollama を使ってローカルで実行することも、DeepSeek などのクラウド AI に接続することもできます。
• 高度な設定機能：インデックス作成のパラメーター、エージェントの動作（ループのステップ数や改善の反復回数など）、コンテキスト処理の上限、要約などのタスクに使用する特定の LLM モデルを微調整するための環境変数を豊富に用意しています。

プロジェクトの状況とロードマップ

現在の状況： CodeCompass は、次のような中核機能の実装を完了しています。

• Qdrant Vector Store を使ったコードベース分析。
• インテリジェントな AI の提案を実現する Agentic RAG（Retrieval Augmented Generation）。
• Ollama を介したローカル LLM（例：llama3.1:8b、nomic-embed-text:v1.5）や、DeepSeek などのクラウドベースの LLM との柔軟な連携。

プロジェクトは積極的にメンテナンスされており、現在の機能セットは安定していると考えられています。

今後の機能強化（検討中）： 中核機能は堅牢ですが、今後の方向性として次のような可能性があります。

• より幅広い LLM プロバイダーへの対応（例：OpenAI、Gemini、Claude）。
• より高度なエージェント機能と、追加のツール連携。
• コンテキスト取得の精度をさらに高める、リポジトリのインデックス作成手法の強化。
• ユーザー設定の簡素化と、さらにスムーズなセットアップ体験。
• さまざまな IDE や開発ワークフローとの、より深い連携。

今後の開発に向けたコミュニティからの貢献や提案を歓迎します。CONTRIBUTING.md をご覧ください。

前提条件

• Node.js v20+（nodejs.org）
• Qdrant 用の Docker（docker.com）
• Ollama（ollama.com）：ローカル LLM と埋め込み機能に使用します。
  • 必要なモデル（環境変数で設定できます。詳しくは「設定」セクションをご覧ください）：
    • 埋め込みモデル：nomic-embed-text:v1.5（デフォルト）
    • 提案モデル（提案に Ollama を使用する場合）：llama3.1:8b（デフォルト）
• DeepSeek API Key（任意。クラウドベースの提案に使用。取得先：Deepseek）

インストール

1. Ollama をインストールする：

   • Linux：

     curl -fsSL https://ollama.com/install.sh | sh
     

   • macOS/Windows：ollama.com からダウンロードします。
   • Ollama アプリケーションが実行中であることを確認します（CLI 版をインストールした場合は、ターミナルで ollama serve を実行します）。
   • デフォルトのモデル（または設定する予定のモデル）をプルします：

     ollama pull nomic-embed-text:v1.5  # Default embedding model
     ollama pull llama3.1:8b            # Default Ollama suggestion model
     

     インストール済みのモデルは ollama list で確認できます。

2. Qdrant をインストールする：

   docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
   

   http://localhost:6333/dashboard で確認します。

3. CodeCompass をインストールする：

   npx -y @alvinveroy/codecompass@latest
   

   CodeCompass がグローバルにインストールされます。以降は、どのディレクトリからでも実行できます。

使用方法

CodeCompass は、サーバーとして実行するモード（デフォルト）と、実行中のサーバーに対して特定のツールを実行するクライアントとしてのモードの 2 つの方法で実行できます。

1. CodeCompass サーバーを実行する：

CodeCompass サーバーを起動するには、Git リポジトリのルートに移動して、次を実行します：

codecompass [repoPath] [--port <number>]

• [repoPath]（任意）：CodeCompass に分析させるリポジトリのパスです。省略した場合は、現在のディレクトリ（.）がデフォルトで使用されます。
• --port <number>（任意）：サーバーの HTTP ポートを指定します。HTTP_PORT 環境変数およびデフォルトのポート（3001）より優先されます。

例：

# Start server for the current directory on the default port
codecompass

# Start server for a specific repository
codecompass /path/to/your/project

# Start server for the current directory on port 3005
codecompass --port 3005

起動すると、CodeCompass は（まだインデックス化されていない場合）リポジトリのインデックス化を開始します。MCP 通信は主に stdio 経由で行われます。また、ヘルスチェック、インデックス化のステータス確認、Git フックからのリポジトリ更新通知の受信に使用するユーティリティ HTTP サーバーも、設定されたポート（デフォルトは 3001）で実行されます。

ユーティリティ HTTP サーバーのポート競合： 設定されたユーティリティ HTTP ポートが別の CodeCompass インスタンスで使用中の場合、新しいインスタンスは独自のユーティリティ HTTP サーバーを無効にし、stdio MCP で実行されます。そのユーティリティ関連の MCP ツール（get_indexing_status、trigger_repository_update など）は、既存インスタンスの HTTP ユーティリティエンドポイントにリクエストを自動的に中継します。ポートが CodeCompass 以外のサービスで使用中の場合、新しいインスタンスはエラーをログに記録して終了します。Git フックでは通常、プライマリの CodeCompass インスタンスが実行中の HTTP ポートを指定してください。

2. CLI クライアントモードでツールを実行する：

特定のツールを実行するために、CodeCompass CLI は専用のサーバーインスタンスを起動し、Model Context Protocol（MCP）を使用して stdio 経由で通信します。

codecompass <tool_name> [json_parameters] [--repo <path>] [--json] [--port <number>]

• <tool_name>：実行するツールの名前です（以下の一覧を参照）。
• [json_parameters]（任意）：ツールのパラメーターを含む JSON 文字列です。パラメーターを取らないツールの場合は、省略するか、空の JSON オブジェクト {} を使用できます。
• --repo <path> または -r <path>（任意）：ツールのコンテキストに使用するリポジトリのパスを指定します。デフォルトは現在のディレクトリ（.）です。起動したサーバーはこのリポジトリを使用します。
• --json または -j（任意）：ツールからの生の JSON レスポンスを出力します。スクリプト作成やデバッグに便利です。
• --port <number>（任意）：起動したサーバーインスタンスのユーティリティ HTTP ポートを指定します。主に、起動したサーバーが他のインスタンスと連携する必要がある場合や、ユーティリティポートを特定のポートに設定する必要がある場合の一貫性を保つために使用します。ただし、ツールの MCP 通信は基本的に stdio 経由で行われます。

CLI クライアントで実行できるツール：

• agent_query <json_params>：複雑なクエリに回答するため、機能を統合します。
  • 例：codecompass agent_query '{"query": "How is user authentication handled?", "sessionId": "my-session-123"}'
  • JSON 出力を使用する場合：codecompass agent_query '{"query": "Show me user models"}' --json
• search_code <json_params>：セマンティックコード検索を実行します。
  • 例：codecompass search_code '{"query": "database connection setup"}'
• get_changelog：プロジェクトの CHANGELOG.md を取得します。
  • 例：codecompass get_changelog
• get_indexing_status：リポジトリの現在のインデックス作成状況を取得します。（別の CC インスタンスがプライマリの場合、情報が中継されることがあります）
  • 例：codecompass get_indexing_status --json
• trigger_repository_update：リポジトリの再インデックス作成を開始します。（中継されることがあります）
  • 例：codecompass trigger_repository_update
• switch_suggestion_model <json_params>：提案モデル／プロバイダーを切り替えます。
  • 例：codecompass switch_suggestion_model '{"model": "deepseek-coder", "provider": "deepseek"}'
• get_session_history <json_params>：セッション ID の履歴を取得します。（パラメーターに sessionId が必要です）
  • 例：codecompass get_session_history '{"sessionId": "my-session-123"}'
• generate_suggestion <json_params>：コードの提案を生成します。
  • 例：codecompass generate_suggestion '{"query": "optimize this database query"}'
• get_repository_context <json_params>：リポジトリのコンテキストの概要を提供します。
  • 例：codecompass get_repository_context '{"query": "main API components"}'

一般的な CLI コマンド：

• codecompass --help または codecompass -h：ヘルプメッセージを表示します。
• codecompass --version または codecompass -v：CodeCompass のバージョンを表示します。
• codecompass changelog [--verbose]：プロジェクトの変更履歴を表示します。

---

CodeCompass をセットアップしたら、Cursor やその他の AI ツールで自然言語のプロンプトを使ってバイブコーディングを行い、コードベースと直感的にやり取りできます。Qdrant と Ollama／DeepSeek を活用した Agentic RAG 機能により、AI がコードのコンテキストを理解し、正確な結果を得られます。CLI クライアントモードを使って、CodeCompass のツールと直接やり取りすることもできます。

設定

CodeCompass は設定に環境変数を使用します。これらの変数は、いくつかの方法で設定できます。

1. シェルで直接設定する：現在のセッションで設定するか、シェルのプロファイルスクリプトに追加して永続的に設定します。
2. システム全体で設定する：オペレーティングシステムのレベルで設定します。
3. MCP クライアントの設定から設定する：Cursor や Cline などの MCP クライアント経由で CodeCompass を使用する場合、それぞれの設定ファイル（例：Cursor の mcp.json）内で環境変数を定義できることがよくあります。詳しくは「Setting Up with Cursor」セクションをご覧ください。
4. .env ファイルを使用する：特にローカル開発時に便利な方法です。CodeCompass で分析するリポジトリのルートディレクトリに .env ファイルを配置できます。CodeCompass はこのファイルから変数を読み込みます。

以下では、シェルまたはシステム全体で環境変数を直接設定する手順と、一般的な変数の一覧を説明します。

環境変数の設定

Linux および macOS の場合：

export コマンドを使用すると、現在のターミナルセッションで環境変数を設定できます。

export VAR_NAME="value"

例：

export LLM_PROVIDER="deepseek"
export DEEPSEEK_API_KEY="your_deepseek_api_key_here"

これらの設定は現在のセッションでのみ有効です。永続化するには、次の export 行をシェルの設定ファイルに追加してください。

• Bash（一般的なデフォルト）：~/.bashrc または ~/.bash_profile
• Zsh（macOS で一般的）：~/.zshrc ファイルを編集した後、再読み込みする（例：source ~/.bashrc または source ~/.zshrc）か、新しいターミナルを開いてください。

Windows の場合：

コマンドプロンプト（cmd.exe）を使用する場合：

set VAR_NAME="value"

例：

set LLM_PROVIDER="deepseek"
set DEEPSEEK_API_KEY="your_deepseek_api_key_here"

この設定は現在のコマンドプロンプトセッションでのみ有効です。

PowerShell を使用する場合：

$Env:VAR_NAME = "value"

例：

$Env:LLM_PROVIDER = "deepseek"
$Env:DEEPSEEK_API_KEY = "your_deepseek_api_key_here"

この設定は現在の PowerShell セッションでのみ有効です。

Windows で環境変数を永続的に設定するには：

1. スタートメニューで「環境変数」を検索します。
2. 「システム環境変数の編集」をクリックします。
3. 「システムのプロパティ」ウィンドウで、「環境変数...」ボタンをクリックします。
4. ユーザー環境変数（現在のユーザー用）またはシステム環境変数（すべてのユーザー用）を設定できます。目的のセクションで「新規...」をクリックします。
5. 変数名（例：LLM_PROVIDER）と値（例：deepseek）を入力します。
6. すべてのウィンドウで「OK」をクリックします。変更を完全に反映するには、コマンドプロンプト、PowerShell、またはコンピューターを再起動する必要がある場合があります。

または、コマンドプロンプトからユーザー環境変数を永続的に設定することもできます（変更を反映するには、新しいコマンドプロンプトを開く必要があります）。

setx VAR_NAME "value"

例：

setx LLM_PROVIDER "deepseek"
setx DEEPSEEK_API_KEY "your_deepseek_api_key_here"

一般的な環境変数（リファレンス）

重要な環境変数の一覧を以下に示します。.env ファイルを使用する場合は、この構成をコピーできます。

# --- General Configuration ---
# LOG_LEVEL: Logging level (e.g., error, warn, info, verbose, debug, silly). Default: info
# LOG_LEVEL=info

# --- Qdrant Configuration ---
# QDRANT_HOST: URL for the Qdrant vector store server.
QDRANT_HOST=http://localhost:6333
# COLLECTION_NAME: Name of the Qdrant collection for this repository.
# It's good practice to use a unique name per repository if you manage multiple.
# COLLECTION_NAME=codecompass_default_collection
# QDRANT_SEARCH_LIMIT_DEFAULT: Default number of results to fetch from Qdrant during standard searches. Default: 10
# QDRANT_SEARCH_LIMIT_DEFAULT=10

# --- Ollama Configuration (for local LLM and embeddings) ---
# OLLAMA_HOST: URL for the Ollama server.
OLLAMA_HOST=http://localhost:11434

# --- LLM Provider Configuration ---
# LLM_PROVIDER: Specifies the primary LLM provider for generating suggestions.
# Supported values: "ollama", "deepseek", "openai", "gemini", "claude". Default: "ollama"
LLM_PROVIDER=ollama

# SUGGESTION_MODEL: The specific model to use for suggestions.
# If LLM_PROVIDER="ollama", example: "llama3.1:8b", "codellama:7b"
# If LLM_PROVIDER="deepseek", example: "deepseek-coder"
# If LLM_PROVIDER="openai", example: "gpt-4-turbo-preview", "gpt-3.5-turbo"
# If LLM_PROVIDER="gemini", example: "gemini-pro"
# If LLM_PROVIDER="claude", example: "claude-2", "claude-3-opus-20240229"
# Default for Ollama: "llama3.1:8b"
SUGGESTION_MODEL=llama3.1:8b

# EMBEDDING_PROVIDER: Specifies the provider for generating embeddings.
# Currently, "ollama" is the primary supported embedding provider. Default: "ollama"
EMBEDDING_PROVIDER=ollama

# EMBEDDING_MODEL: The specific model to use for embeddings via Ollama.
# Default: "nomic-embed-text:v1.5"
EMBEDDING_MODEL=nomic-embed-text:v1.5

# --- Cloud Provider API Keys (only needed if using respective providers) ---
# DEEPSEEK_API_KEY: Your API key for DeepSeek.
# DEEPSEEK_API_KEY=your_deepseek_api_key_here

# OPENAI_API_KEY: Your API key for OpenAI.
# OPENAI_API_KEY=your_openai_api_key_here

# GEMINI_API_KEY: Your API key for Google Gemini.
# GEMINI_API_KEY=your_gemini_api_key_here

# CLAUDE_API_KEY: Your API key for Anthropic Claude.
# CLAUDE_API_KEY=your_claude_api_key_here

# --- DeepSeek Specific (Optional) ---
# DEEPSEEK_API_URL: Custom API URL for DeepSeek if not using the default.
# Default: "https://api.deepseek.com/chat/completions"
# DEEPSEEK_API_URL=https://api.deepseek.com/chat/completions
# DEEPSEEK_RPM_LIMIT: Requests per minute limit for DeepSeek. Default: 20
# DEEPSEEK_RPM_LIMIT=20

# --- Agent Configuration ---
# MAX_FILES_FOR_SUGGESTION_CONTEXT_NO_SUMMARY: Maximum number of files to list directly in the generate_suggestion tool's context
# before attempting to summarize the file list using an LLM. Default: 15
# MAX_FILES_FOR_SUGGESTION_CONTEXT_NO_SUMMARY=15

# MAX_SNIPPET_LENGTH_FOR_CONTEXT_NO_SUMMARY: Maximum length of a code snippet to include in context without summarization.
# Snippets longer than this will be summarized by an LLM if available. Default: 1500
# MAX_SNIPPET_LENGTH_FOR_CONTEXT_NO_SUMMARY=1500

# MAX_DIFF_LENGTH_FOR_CONTEXT_TOOL: Maximum length of a git diff to include in context without summarization.
# Diffs longer than this will be summarized by an LLM if available. Default: 3000
# MAX_DIFF_LENGTH_FOR_CONTEXT_TOOL=3000

# AGENT_DEFAULT_MAX_STEPS: Default maximum number of steps (tool calls or LLM responses) the agent will take. Default: 10
# AGENT_DEFAULT_MAX_STEPS=10

# AGENT_ABSOLUTE_MAX_STEPS: Absolute maximum number of steps the agent can take, even if it requests more. Default: 15
# AGENT_ABSOLUTE_MAX_STEPS=15

# MAX_REFINEMENT_ITERATIONS: Maximum number of iterations for query refinement. Default: 3
# MAX_REFINEMENT_ITERATIONS=3

# FILE_INDEXING_CHUNK_SIZE_CHARS: Target size for chunks when indexing large files (in characters). Default: 1000
# FILE_INDEXING_CHUNK_SIZE_CHARS=1000

# FILE_INDEXING_CHUNK_OVERLAP_CHARS: Overlap between chunks when indexing large files (in characters). Default: 200
# FILE_INDEXING_CHUNK_OVERLAP_CHARS=200

# SUMMARIZATION_MODEL: LLM model to use for summarization tasks (e.g., long diffs, long snippets).
# If empty or not set, defaults to the SUGGESTION_MODEL.
# SUMMARIZATION_MODEL= # Example: llama3.1:8b or deepseek-coder

# REFINEMENT_MODEL: LLM model to use for LLM-powered query refinement.
# If empty or not set, defaults to the SUGGESTION_MODEL.
# REFINEMENT_MODEL= # Example: llama3.1:8b or deepseek-coder

# REQUEST_ADDITIONAL_CONTEXT_MAX_SEARCH_RESULTS: Number of search results to fetch when agent uses 'request_additional_context' with type 'MORE_SEARCH_RESULTS'. Default: 20
# REQUEST_ADDITIONAL_CONTEXT_MAX_SEARCH_RESULTS=20

# AGENT_QUERY_TIMEOUT: Timeout in milliseconds for agent's LLM reasoning steps. Default: 180000 (3 minutes)
# AGENT_QUERY_TIMEOUT=180000

注：環境変数を直接、または MCP クライアントの設定を通じて設定する場合、.env ファイルを作成する必要はありません。上記の一覧は、変数名とその用途のリファレンスです。Ollama を使用するローカル環境では、多くの場合デフォルト設定のままで動作するため、モデルやプロバイダーをカスタマイズする場合を除き、多くの環境変数を設定する必要はありません。DeepSeek などのクラウドプロバイダーを使用する場合は、該当する API_KEY を設定し、LLM_PROVIDER と SUGGESTION_MODEL を調整する必要があります。 HTTP ポートは、サーバーの起動時に --port <number> CLI 引数で設定することもできます。この値は HTTP_PORT 環境変数およびデフォルト値より優先されます。

トラブルシューティング

• モデルが見つからない（Ollama）：

  • ollama pull <model_name> を使用して、正しいモデル名のモデルをプルしたことを確認してください。
  • ollama list でインストール済みのモデルを確認してください。
  • OLLAMA_HOST 環境変数が正しく設定されており、Ollama サーバーにアクセスできることを確認してください。
  • SUGGESTION_MODEL（提案に Ollama を使用する場合）および EMBEDDING_MODEL 環境変数が、プル済みのモデルと一致していることを確認してください。

• 接続が拒否される（Ollama/Qdrant）：

  • Ollama サーバーが実行中であることを確認してください（例：ollama serve または Ollama アプリケーション）。
  • Qdrant の Docker コンテナが実行中（docker ps）で、設定されたホスト／ポート（デフォルトは http://localhost:6333）からアクセスできることを確認してください。
  • ファイアウォールの設定によってローカル接続がブロックされている可能性がある場合は、設定を確認してください。

• API キーの問題（DeepSeek、OpenAI、Gemini、Claude）：

  • 該当する API キー（例：DEEPSEEK_API_KEY）が、環境変数または .env ファイルに正しく設定されていることを再確認してください。
  • キーが有効で、有効期限が切れておらず、クォータに達していないことを確認してください。
  • DeepSeek の場合、（使用環境で利用可能であれば）npm run test-deepseek スクリプトを使用して、接続の問題を診断できます。

• プロバイダーとモデルの不一致：

  • LLM_PROVIDER と SUGGESTION_MODEL の環境変数に互換性があることを確認してください（例：LLM_PROVIDER=deepseek の場合は、deepseek-coder のような DeepSeek のモデル名を使用します）。

• 一般的な問題：

  • 詳細なエラーメッセージについては、CodeCompass のログを確認してください。より詳細な出力を表示するには、LOG_LEVEL=debug を設定する必要がある場合があります。
  • Node.js と Docker が正しくインストールされ、実行中であることを確認してください。

Cursor の設定

1. ~/.cursor/mcp.json を編集します。

   {
     "mcpServers": {
       "codecompass": {
         "command": "npx",
         "args": ["-y", "@alvinveroy/codecompass@latest", "/path/to/your/repo"],
         "env": {
           "DEEPSEEK_API_KEY": "your_deepseek_api_key"
         }
       }
     }
   }
   

2. your_deepseek_api_key を DeepSeek の API キーに置き換えます（Ollama を使用する場合は省略できます）。「Configuration」セクションに記載されている任意の環境変数（例：LLM_PROVIDER、SUGGESTION_MODEL）を、この env ブロック内に設定できます。CodeCompass は設定された環境変数を使用します。
3. Cursor を再起動します。

注：VSCode で Cline を使用する場合は、cline_mcp_settings.json でも同様に設定してください（Cline のドキュメントを参照）。この方法で設定した環境変数も、CodeCompass に認識されます。

貢献

フォークしてブランチを作成し、プルリクエストを送信してください。CONTRIBUTING.md を参照してください。

ライセンス

MIT ライセンス。

監査