Claude Context Local

🚀 クラウドを必要としないClaudeコンテキスト

EmbeddingGemmaを使用して100%ローカルで実行される意味論的コード検索。APIキー不要、コスト不要、あなたのコードは決してあなたのマシンを離れません。

Claudeのコードコンテキストは強力ですが、コードをクラウドに送信するとトークンが消費され、プライバシーの問題も生じます。このプロジェクトは、意味論的コード検索を完全にあなたのマシン上で行います。MCP（Model Context Protocol）を介してClaude Codeと統合されているため、同じワークフローを維持しながら、より高速、低コスト、かつプライベートに利用できます。

• 🔍 文字列ではなく意味でコードを検索
• 🔒 100%ローカル - 完全にプライベート
• 💰 APIコストゼロ - 永久無料
• ⚡ Claude Codeでのトークン消費を削減し、高速なローカル検索

🚀 クイックスタート

1) MCPサーバーを登録する（標準入出力）

claude mcp add code-search --scope user -- uv run --directory ~/.local/share/claude-context-local python mcp_server/server.py

その後、Claude Codeを開くと、サーバーがuv環境内で標準入出力モードで実行されます。

2) コードベースをインデックス化する

Claude Codeを開き、「index this codebase」と入力します。手動でのコマンドは必要ありません。

3) Claude Codeで使用する

Claude Code内のチャットで対話します。関数呼び出しやコマンドは必要ありません。

✨ 主な機能

• 多言語対応：9種類以上のプログラミング言語と15種類のファイル拡張子をサポート
• インテリジェントチャンキング：ASTベース（Python）+ tree-sitter（JS/TS/Go/Java/Rust/C/C++/C#）
• 意味論的検索：自然言語クエリですべての言語のコードを検索
• 豊富なメタデータ：ファイルパス、フォルダ構造、意味論的タグ、言語固有の情報
• MCP統合：Claude Codeと直接統合
• ローカル処理：すべての埋め込みデータがローカルに保存され、API呼び出しは不要
• 高速検索：FAISSを使用した効率的な類似性検索

📦 インストール

インストール（ワンライナー）

curl -fsSL https://raw.githubusercontent.com/FarhanAliRaza/claude-context-local/main/scripts/install.sh | bash

システムにcurlがインストールされていない場合は、wgetを使用できます。

wget -qO- https://raw.githubusercontent.com/FarhanAliRaza/claude-context-local/main/scripts/install.sh | bash

既存のインストールを更新する

同じインストールコマンドを実行して更新します。

curl -fsSL https://raw.githubusercontent.com/FarhanAliRaza/claude-context-local/main/scripts/install.sh | bash

インストーラーは以下のことを行います。

• 既存のインストールを検出する
• ~/.claude_code_search内の埋め込みデータとインデックス化されたプロジェクトを保持する
• 自動的にローカルの変更を退避する（curlで実行する場合）
• コードと依存関係を更新する

💻 使用例

基本的な使用法

# MCPサーバーを登録する
claude mcp add code-search --scope user -- uv run --directory ~/.local/share/claude-context-local python mcp_server/server.py

# コードベースをインデックス化する
# Claude Code内で「index this codebase」と入力

# Claude Code内でコードを検索する
# チャットで自然言語クエリを入力

📚 ドキュメント

アーキテクチャ

claude-context-local/
├── chunking/                         # 多言語チャンキング（15種類の拡張子）
│   ├── multi_language_chunker.py     # 統一的なオーケストレーター（Python AST + tree-sitter）
│   ├── python_ast_chunker.py         # Python固有のチャンキング（豊富なメタデータ）
│   └── tree_sitter.py                # tree-sitter: JS/TS/JSX/TSX/Svelte/Go/Java/Rust/C/C++/C#
├── embeddings/
│   └── embedder.py                   # EmbeddingGemma; デバイス=自動（CUDA→MPS→CPU）; オフラインキャッシュ
├── search/
│   ├── indexer.py                    # FAISSインデックス（デフォルトはCPU; 利用可能な場合はGPU）
│   ├── searcher.py                   # インテリジェントなランキングとフィルター
│   └── incremental_indexer.py        # Merkle駆動の増分インデックス化
├── merkle/
│   ├── merkle_dag.py                 # ワークスペースのコンテンツハッシュDAG
│   ├── change_detector.py            # スナップショットを比較して変更されたファイルを検出
│   └── snapshot_manager.py           # スナップショットの永続化と統計情報
├── mcp_server/
│   └── server.py                     # Claude Code用のMCPツール（標準入出力/HTTP）
└── scripts/
    ├── install.sh                    # ワンライナーのリモートインストーラー（uv + モデル + faiss）
    ├── download_model_standalone.py  # 埋め込みモデルを事前に取得
    └── index_codebase.py             # スタンドアロンのインデックス化ユーティリティ

データフロー

graph TD
    A["Claude Code (MCP client)"] -->|index_directory| B["MCP Server"]
    B --> C{IncrementalIndexer}
    C --> D["ChangeDetector<br/>(Merkle DAG)"]
    C --> E["MultiLanguageChunker"]
    E --> F["Code Chunks"]
    C --> G["CodeEmbedder<br/>(EmbeddingGemma)"]
    G --> H["Embeddings"]
    C --> I["CodeIndexManager<br/>(FAISS CPU/GPU)"]
    H --> I
    D --> J["SnapshotManager"]
    C --> J
    B -->|search_code| K["Searcher"]
    K --> I

インテリジェントチャンキング

このシステムは、高度なパースを使用して、サポートされているすべての言語で意味論的に意味のあるチャンクを作成します。

チャンキング戦略

• Python：豊富なメタデータを抽出するためのASTベースのパース
• その他のすべての言語：言語固有のノードタイプを認識するtree-sitterパース

抽出されるチャンクタイプ

• 関数/メソッド：シグネチャ、ドキュメント文字列、デコレーターを含む完全なもの
• クラス/構造体：メンバー関数を別のチャンクとして含む完全な定義
• インターフェース/トレイト：型定義と契約
• 列挙型/定数：値定義とモジュールレベルの宣言
• 名前空間/モジュール：組織構造
• テンプレート/ジェネリック：パラメータ化された型定義

すべての言語に対する豊富なメタデータ

• ファイルパスとフォルダ構造
• 関数/クラス/型の名前と関係
• 言語固有の機能（非同期、ジェネリック、修飾子など）
• 親子関係（クラス内のメソッド）
• 正確なコード位置の行番号
• 意味論的タグ（コンポーネント、エクスポート、非同期など）

設定

環境変数

• CODE_SEARCH_STORAGE：カスタムストレージディレクトリ（デフォルト: ~/.claude_code_search）

モデル設定

システムはデフォルトでgoogle/embeddinggemma-300mを使用します。

注意事項：

• ダウンロードサイズ：バリアントとキャッシュによって異なり、ディスク上で約1.2 - 2GB
• デバイス選択：自動（NVIDIAではCUDA、Apple SiliconではMPS、それ以外はCPU）
• インストーラーを介して事前にダウンロードするか、初回使用時にダウンロードできます
• FAISSバックエンド：デフォルトはCPU。NVIDIA GPUが検出された場合、インストーラーはfaiss-gpu-cu12（またはfaiss-gpu-cu11）をインストールしようとし、インデックスは実行時に自動的にGPUで動作しますが、ポータビリティのためにCPUとして保存されます。

Hugging Face認証（必要な場合）

google/embeddinggemma-300mモデルはHugging Faceにホストされており、ダウンロードには利用規約の受諾や認証が必要になる場合があります。

1. モデルページにアクセスし、利用規約を受諾します。
   • https://huggingface.co/google/embeddinggemma-300m
2. 以下のいずれかの方法で認証します。
   • CLI（推奨）：

     uv run huggingface-cli login
     # https://huggingface.co/settings/tokens からトークンを貼り付ける
     

   • 環境変数：

     export HUGGING_FACE_HUB_TOKEN=hf_XXXXXXXXXXXXXXXXXXXXXXXX
     

初回の成功したダウンロード後、モデルは~/.claude_code_search/modelsにキャッシュされ、速度と信頼性のためにオフラインでの読み込みが優先されます。

サポートされる言語と拡張子

完全にサポートされる（9種類以上の言語で15種類の拡張子）

合計：9種類以上のプログラミング言語で15種類のファイル拡張子

ストレージ

データは設定されたストレージディレクトリに保存されます。

~/.claude_code_search/
├── models/          # ダウンロードされたモデル
├── index/           # FAISSインデックスとメタデータ
│   ├── code.index   # ベクトルインデックス
│   ├── metadata.db  # チャンクメタデータ（SQLite）
│   └── stats.json   # インデックス統計情報

パフォーマンス

• モデルサイズ：約1.2GB（EmbeddingGemma-300mとキャッシュ）
• 埋め込み次元：768（速度のために減らすことができます）
• インデックスタイプ：データセットのサイズに基づいて、Flat（正確）またはIVF（近似）
• バッチ処理：埋め込み生成のための設定可能なバッチサイズ

ヒント：

• 大規模なリポジトリの最初のインデックス化には時間がかかります（モデルの読み込み + チャンキング + 埋め込み）。その後の実行は増分的です。
• GPUを使用したFAISSでは、大規模なインデックスの検索が大幅に高速化されます。
• 利用可能な場合、埋め込みは自動的にCUDA（NVIDIA）またはMPS（Apple）を使用します。

トラブルシューティング

一般的な問題

1. インポートエラー：uv syncですべての依存関係がインストールされていることを確認してください。
2. モデルのダウンロードに失敗する：インターネット接続とディスク容量を確認してください。
3. メモリの問題：インデックス化スクリプトのバッチサイズを減らしてください。
4. 検索結果がない：コードベースが正常にインデックス化されたことを確認してください。
5. FAISS GPUが使用されない：nvidia-smiが利用可能で、CUDAドライバーがインストールされていることを確認し、インストーラーを再実行してfaiss-gpu-cu12/cu11を選択してください。
6. 強制的にオフラインにする：ローカルキャッシュを自動検出し、オフラインでの読み込みを優先します。HF_HUB_OFFLINE=1を設定することもできます。

無視するディレクトリ（速度とノイズの削減のため）

node_modules, .venv, venv, env, .env, .direnv, __pycache__, .pytest_cache, .mypy_cache, .ruff_cache, .pytype, .ipynb_checkpoints, build, dist, out, public, .next, .nuxt, .svelte-kit, .angular, .astro, .vite, .cache, .parcel-cache, .turbo, coverage, .coverage, .nyc_output, .gradle, .idea, .vscode, .docusaurus, .vercel, .serverless, .terraform, .mvn, .tox, target, bin, obj

🔧 技術詳細

このシステムは、GoogleのEmbeddingGemmaモデルと高度な多言語チャンキングを使用して、15種類のファイル拡張子と9種類以上のプログラミング言語にわたる意味論的検索機能を提供します。MCP（Model Context Protocol）を介してClaude Codeと統合されています。

📄 ライセンス

このプロジェクトはGNU General Public License v3.0（GPL-3.0）の下でライセンスされています。詳細はLICENSEファイルを参照してください。

インスピレーション

このプロジェクトは、zilliztech/claude-contextにインスピレーションを得ています。私はこれらの概念をPython実装に適応させ、完全にローカルな埋め込みを実現しました。