vibe-hnindex

---

このツールについて

vibe-hnindex は、Model Context Protocol サーバーです。フォルダーを一度インデックス化すると、アシスタント（Claude、Cursor、Windsurf、Antigravity など）がパスと行範囲を指定して、そのコードベースを検索できるようになります。データはローカルに保存されます（SQLite + オプションの Qdrant）。埋め込みには Ollama（デフォルト）、OpenAI、Voyage、Gemini、または OpenAI 互換 API を使用できます。詳しくは埋め込みプロバイダーをご覧ください。クラウドプロバイダーには、埋め込み対象のコンテンツが送信されます。ベクトルの保存には Qdrant（Docker、ローカル、または QDRANT_API_KEY を使った Qdrant Cloud）を使用します。

---

ドキュメント

📚 ドキュメントサイト全文：docs.hnindex.cloud — はじめに、設定、ツールリファレンス、ガイド、コードエージェントを網羅する16ページです。

ページ	学べる内容
概要	vibe-hnindex の機能、主な特長、仕組み
インストール	Node、Ollama、Qdrant のセットアップと MCP 設定
クイックスタート	CLI + エージェントスキルを使った5分間のガイド
設定	埋め込みモデルの比較を含む、25個以上の環境変数すべて
検索	6つの検索モード、正規表現、あいまい検索、ストリーミング、キャッシュ
コードエージェント 🆕	安全スコープ付きの code_session + code_apply
MCP のセットアップ	プラットフォーム別の設定（Claude、Cursor、Antigravity、VS Code など）

リポジトリ内のドキュメントも利用できます：docs/getting-started.md、docs/configuration.md、docs/tools-reference.md。

---

CLI インストーラー（hnindex）

任意 — MCP の JSON または Codex の TOML を自動で書き込みます（既存の設定を安全にマージし、ドキュメントと同じ npx -y vibe-hnindex ブロックを使用します）。

npm install -g hnindex-cli

# Setup MCP config
hnindex init --mcp antigravity    # or: claude, cursor, windsurf, vscode, codex
hnindex init --list               # show all targets and paths

# Install AI agent skill (recommended)
hnindex init-skill --target claude    # or: antigravity, cursor, windsurf, vscode
hnindex init-skill --list             # show all skill targets

# Update
hnindex update                    # npm update -g hnindex-cli

詳しいドキュメントは docs.hnindex.cloud をご覧ください。

---

5 ステップでインストール

1. Node.js — v22 以上（nodejs.org）。CI では Node 22 と 24 を検証しています。SQLite は、サポート対象プラットフォーム向けにバンドルされた N-API バイナリを使用します。npm i vibe-hnindex が失敗する場合は、トラブルシューティング → Windows を参照してください。
2. 埋め込みプロバイダー — OpenAI、Voyage、Gemini または互換 APIを選ぶか、ローカルの Ollama を使用します。ollama.com からインストールし、ollama pull bge-m3:567m を実行して、ollama serve を起動したままにします（または OLLAMA_URL にリモートサーバーを設定します）。
3. Qdrant — セマンティック検索／ハイブリッド検索を行う場合：docker run -d --name qdrant -p 6333:6333 qdrant/qdrant を実行します（または Qdrant Cloud を使用します）。キーワードのみの検索では Qdrant は不要です。
4. MCP 設定 — アシスタントの MCP 設定にサーバーを追加します。最小限の例（セルフホストの Qdrant）：

{
  "mcpServers": {
    "vibe-hnindex": {
      "command": "npx",
      "args": ["-y", "vibe-hnindex"],
      "env": {
        "OLLAMA_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "bge-m3:567m",
        "QDRANT_URL": "http://localhost:6333",
        "SEARCH_STREAM_ENABLED": "true",
        "CODE_AGENT_ENABLED": "true",
        "CODE_AGENT_SCOPE": "moderate",
        "CHAT_MEMORY_ENABLED": "true"
      }
    }
  }
}

5. IDE またはアシスタントを再起動してから、チャットでパスのインデックス作成と検索を依頼します。最初のステップを参照してください。

Qdrant Cloud の場合は、QDRANT_API_KEY を追加し、QDRANT_URL に HTTPS クラスターの URL を設定します。詳しくははじめにを参照してください。

エージェントワークスペース（v0.15.0）

workspace_context は、アクティブなプロジェクトの目的、Git／インデックスの状態、プロジェクト／セッションごとに永続化される宣言済みのタスクを特定します。locate_code は、まずファイル／シンボルを検索し、次にローカルでキーワードを検索して、行の根拠と鮮度を返します。明示的なハイブリッドモードでは、設定済みのセマンティック API を使用します。MCP 起動手順と knowledge://workspace で、このワークフローを利用できます。プロジェクト単位の CLI インストールではルートが自動的に設定されます。グローバルインストールでは、明示的に設定されていない限り、クライアントのルートに従います。

ワークスペースとコードの場所を参照してください。編集前に古くなった位置情報を更新してください。利用できないコードや除外されたコードには、ファイルシステムツールを使用してください。

コードグラフ（v0.14.0）

SQLite のみを使用して、index_code_graph(path, project_name) で TypeScript／JavaScript のシンボルグラフを構築できます。index_codebase でも構築され、ファイルのインデックス作成や監視によって関係性が自動的に更新されます。find_references、callers、graph_context を使って、ソースの根拠と範囲を限定した関係コンテキストを確認できます。グラフデータベースサービスは不要です。

AST チャンク分割では、可能な限り関数／クラスの境界が保持されます。アップグレード後に index_codebase を一度実行し、チャンクとベクトルを再構築してください。解決の制限、オフラインでの使用、トークン予算、品質評価については、コードグラフガイドを参照してください。

オプションの再ランク付け

ハイブリッド検索では、キーワード検索の結果と埋め込みベクトルを RRF で組み合わせます。オプションの再ランク付けでは、Voyage（RERANK_PROVIDER=voyage、VOYAGE_API_KEY または RERANK_API_KEY）と カスタム HTTP（RERANK_PROVIDER=http、RERANK_URL）をサポートしています。再ランク付け機能がない場合や失敗した場合は、元の検索順位が維持されます。完全一致のシンボル／正規表現モードでは、再ランク付けはスキップされます。

環境変数	役割
SEARCH_RERANK	false に設定すると再ランク付けが無効になります。
SEARCH_RERANK_POOL	最終的な絞り込み前の候補プール（デフォルトは 50。要求された上限以上）。
RERANK_PROVIDER	none、http、voyage。デフォルトは、RERANK_URL が設定されている場合は http、それ以外は none です。
RERANK_MODEL	Voyage モデル。デフォルトは rerank-3-lite です。
RERANK_URL	カスタムエンドポイント。HTTP の仕様は {query, documents} -> {scores} です。
RERANK_API_KEY	オプションの Bearer 認証情報。Voyage では VOYAGE_API_KEY を使用できます。
RERANK_TIMEOUT_MS	リクエスト／ボディ全体のタイムアウト。デフォルトは 15000 です。

設定を参照してください。

タイムアウト

Ollama または Qdrant が応答しない場合に処理が停止しないよう、vibe-hnindex はすべての外部呼び出しにタイムアウトを適用します。環境変数で調整できます。

環境変数	デフォルト	対象
OLLAMA_TIMEOUT_MS	30000 (30s)	Ollama の /api/embed および /api/tags 呼び出しの最大待機時間
QDRANT_TIMEOUT_MS	15000 (15s)	Qdrant API 呼び出し（検索、upsert など）の最大待機時間
SEARCH_TIMEOUT_MS	60000 (60s)	検索操作全体のタイムアウト

マシンの処理速度が遅い場合やデータセットが大きい場合は、いずれかの値を大きくしてください。そのレイヤーのタイムアウトを無効にするには 0 を設定します（推奨されません）。

Google Antigravity

上記と同じ mcpServers ブロックを使用し、Antigravity の MCP ファイルに保存してください。

ファイル	ユーザーフォルダー内の .gemini/antigravity/ にある mcp_config.json
Windows	C:\Users\<your-username>\.gemini\antigravity\mcp_config.json
macOS / Linux	~/.gemini/antigravity/mcp_config.json
UI	⋮ メニュー → MCP → Manage MCP Servers → View raw config

手順については、Integrations → Google Antigravity を参照してください。

---

機能（概要）

検索	6 つのモード：キーワード（FTS5+BM25）、セマンティック（Qdrant ベクトル）、ハイブリッド（RRF 融合）、正規表現、シンボル、自動
コーディングエージェント	code_session — 1 回の呼び出しで 5～15 回の検索を置き換えます。code_apply — テスト／lint／型チェックを自動実行する安全なコード変更
チャットメモリ 🆕	ツール呼び出しを自動追跡し、Qdrant によるセマンティック検索を行います。セッションをまたいで AI コンテキストを保持します
ストリーミング	キーワード検索とセマンティック検索を並列実行（約 1.5～2 倍高速）、4 段階の進行状況通知
あいまい検索	レーベンシュタイン距離でタイプミスを自動修正します（「fucntion」→「function」）
スマートコンテキスト	タスクを考慮したコンテキスト：影響分析、テストファイルの検出、類似コードパターン
ストレージ	ディスク上の SQLite + ベクトル用の Qdrant。100% ローカルで、クラウドは不要です
インデックス作成	増分処理（SHA-1 ハッシュ）、並列ワーカー（約 3～4 倍高速）、監視モード（保存時に自動で再インデックス）、40 以上の言語、.hnindexignore
耐障害性	Qdrant または Ollama がなくてもキーワード検索が機能します。段階的に機能を縮退します
ベンチマーク	組み込みの benchmark_search ツール — ストリーミングと非ストリーミング、およびすべての検索モードを比較します
複数の埋め込みプロバイダー（v0.13.0）	Ollama、OpenAI、Voyage、Gemini、OpenAI 互換 API。プロバイダー／モデルを考慮したベクトルコレクション
複数の埋め込みモデル	bge-m3（デフォルト）、nomic-embed-text、qwen3-embedding、mxbai-embed-large など

---

アーキテクチャ

graph TB
    subgraph Input["📂 Input"]
        A["💻 Your Codebase<br/>.ts .py .go .rs ..."]
    end

    subgraph Server["⚙️ vibe-hnindex MCP Server"]
        B["🔍 Search Router<br/>keyword | semantic | hybrid"]
        C["🔀 RRF Fusion"]
    end

    subgraph Storage["💾 Storage"]
        D[("SQLite<br/>FTS5 + Keyword")]
        E[("Qdrant<br/>Vector Embeddings")]
    end

    subgraph Memory["🧠 Chat Memory (v0.12)"]
        F[("SQLite<br/>Chat Context")]
        G[("Qdrant<br/>Chat Vectors")]
    end

    subgraph Infra["🏗️ Infrastructure"]
        H["Ollama<br/>Embeddings"]
        I["Qdrant<br/>localhost:6333"]
    end

    subgraph Output["🤖 AI Clients"]
        J["Claude · Cursor · Windsurf<br/>Antigravity · VS Code"]
    end

    A -->|"index_codebase"| Storage
    A -->|scan| H
    B -->|"keyword"| D
    B -->|"semantic"| E
    B -->|"hybrid"| C
    C --> D
    C --> E
    B -.->|"auto-track"| F
    F --> H
    H --> G
    D --> J
    E --> J
    H -.-> I

    style F fill:#6366f1,color:#fff
    style G fill:#6366f1,color:#fff
    style B fill:#f59e0b,color:#000
    style J fill:#22c55e,color:#fff

インデックス作成と検索の仕組み →

---

ライセンス

MIT — LICENSE を参照してください。

コントリビューション

Issue と PR：github.com/AndyAnh174/vibe-hnindex。

お問い合わせ

Ho Viet Anh (AndyAnh174) · [email protected] · GitHub

Codex とアーキテクチャ（v0.15.2）

プロジェクト内で npx -y hnindex-cli init --mcp codex を実行し、必要に応じて npx -y hnindex-cli init-skill --target codex を実行してください。Codex のプロジェクト MCP は .codex/config.toml を使用します（信頼済みプロジェクトのみ）。スキルは .agents/skills/use-vibe-hnindex を使用します。Codex を再起動／再接続し、workspace_context を依頼してから index_code_graph を依頼してください。

CLI の設定、システム図、シーケンス図、ユーザー図、Codex の公式 MCP 設定を参照してください。