semhood

semhood

grep はもう不要です。 キーワードではなく意図から、AI エージェントに必要なコードを正確に見つけます。semhood は AST を認識するセマンティックコード検索エンジンです。呼び出しグラフのコンテキストと、オプションの LLM による拡充情報を含め、コードの機能に基づいて取得します。

API キー不要で完全にオフラインで動作します。または、クラウドの埋め込みモデル、コードに特化した Voyage のモデル、あるいは汎用性の高い OpenAI の（自然言語向け）埋め込みモデルを接続して、検索精度を高めることもできます。オプションの LLM による拡充機能では、各チャンクにロジックの要約と開発者向けのクエリが追加されます。これらは一度コミットして共有できます。また、すべての検索結果には呼び出しグラフ（そのコードが呼び出すものと、そのコードを呼び出すもの）が含まれます。

semhood を選ぶ理由 · インストール · クイックスタート · MCP の設定 · アーキテクチャ · 設定 · トラブルシューティング

   ┌──────────────┐    parse + embed     ┌──────────────┐    LLM enrich    ┌──────────────┐
   │  source tree │ ───────────────────► │ code  vector │ ──────────────► │  description │
   │              │                      │ + BM25 sparse│                  │  + queries   │
   └──────────────┘                      └──────────────┘                  └──────────────┘

                                Search via CLI, HTTP, or MCP.

semhood は、開発者の考え方に沿ってコードベースにインデックスを作成します。すべての関数、メソッド、クラスが、呼び出しグラフ、docstring、シグネチャとともにチャンク化されます。意図（「一時的な決済エラーを再試行するには？」）で検索すると、質問に実際に答える少数のチャンクが返されます。

処理は 2 段階です。構造化（常に実行、無料、約数秒）と、拡充（任意。LLM またはコーディングエージェントを使用し、pending キューを処理）です。第 1 段階の完了後にインデックスを検索できます。第 2 段階では、自然言語による検索の精度がさらに高まります。

このパッケージには MCP サーバー が含まれているため、Claude Desktop、Cursor、Cline、Continue、Kiro、Zed など、MCP 対応のクライアントであれば semhood をツールとして呼び出せます。AI エージェントは、組み込みの read_file や grep と並べて search、find_symbol、get_chunk_context を利用できます。

semhood を選ぶ理由

一般的なコード検索では、生のソースコードを埋め込み、自然言語のクエリがその近くにヒットすることを期待します。semhood は、通常のベクトル検索や grep では実現できない 2 つの機能を追加します。

🧠 開発者のように考えるエンリッチメント

LLM が各関数とクラスを読み込み、それぞれ個別の検索ベクトルとして保存される 2 つの成果物を作成します。

• ロジックの要約 — コードが実際に何をするのかを、平易な言葉で説明します。名前でもシグネチャでもなく、動作を説明します。
• 開発者が尋ねると予測される質問 — エンジニアがこのコードを探すときに実際に尋ねる質問です。「失敗した支払いを再試行するには？」、「顧客のメールアドレスはどこで検証されている？」

これが検索を的確にする部分です。質問で検索すると、その質問に答えるものとしてあらかじめラベル付けされた質問と照合されるため、クエリとキーワードがまったく一致しなくても、適切なチャンクが選ばれます。エンリッチメントは一度だけ生成して Git にコミットすれば、チーム全体とすべての AI エージェントが、追加の手間なくより良い検索結果を得られます。→ エンリッチメントのポータビリティ

エンリッチメントが重要な理由：検索できる単語がないコードもあります。 通常のセマンティック検索が機能するのは、ソースに質問に近い言葉が含まれている場合だけです。簡潔すぎる名前、生の数式、ビジネスルールなど、重要であっても言葉が含まれていないコードは数多くあります。次のような関数を考えてみてください。

def _calc(p, r, n):
    return p * (1 + r) ** n

*「複利を計算するには？」*と尋ねても、通常のベクトル検索では何も見つかりません。「interest」も「compound」もなく、ソース内には質問に近い意味を持つものが何もないためです。エンリッチメントはコードを読み込み、次の内容を生成します。

{
  "logic_summary": "Computes compound interest — final balance = principal × (1 + rate)^periods.",
  "developer_queries": [
    "how do we calculate compound interest?",
    "where is the future-value / compounding formula?",
    "how is a balance grown over multiple periods?"
  ]
}

これで、質問は同じ意味を持つ、あらかじめ書かれた質問と一致し、クエリと単語がまったく一致しないにもかかわらず、_calc が最上位に表示されます。難解でも重要な関数は、通常のセマンティック検索では見つからず、エンリッチメントによって見つけられる関数そのものです。

🕸️ すべての検索結果に呼び出しグラフが含まれます

各チャンクは、何を呼び出すか、そして何から呼び出されるかを把握しています。そのため、検索結果は「この関数です」だけではなく、関数とその周辺情報を返します。1 回の get_chunk_context 呼び出しで、本文、calls、called_by がまとめて返されるため、AI エージェントはファイルを開いて参照先を手作業でたどらなくても、呼び出し元と呼び出し先のコンテキストを同じレスポンスで取得できます。

機能

• 検索を強化するエンリッチメント — LLM が各チャンクに、平易な言葉によるロジックの要約と開発者が尋ねると予測される質問を付与し、それぞれを独立したベクトルとしてインデックス化します。これにより、キーワードがまったく一致しない質問形式のクエリでも、適切なコードが見つかります。一度作成して Git にコミットし、チームで共有できます。
• 呼び出しグラフを含む — 各検索結果は、何を呼び出すか、そして何から呼び出されるかを把握しているため、エージェントは関数だけでなく、その周辺情報も取得できます
• Tree-sitter による AST 対応のチャンク化 — すべての関数、メソッド、クラスが、独立した検索単位になります
• ハイブリッド検索 — 高密度ベクトル（code、description、developer_queries）と BM25 スパース検索を、1 つのクエリで利用できます
• AI エージェントのトークン効率を向上 — 数十回の read_file + grep 呼び出しを、1 回の search に置き換えます
• すぐに使える MCP サーバー — Claude Desktop、Cursor、Cline、Continue、Kiro、Zed で動作します
• 10 言語に対応 — Python、JavaScript、TypeScript、Java、Go、PHP、C#、Ruby、Rust、C++
• 無料プランで利用可能 — ローカル埋め込みと構造解析パイプラインは、API キーなしで動作します
• 増分インデックス作成 — --changed を指定すると、git diff で変更されたものだけを再インデックスします

インストール

# Local-only (free, offline embeddings via sentence-transformers)
pip install "semhood[local]"

# With everything: voyage + openai + anthropic + cohere + chroma
pip install "semhood[all]"

# Pick exactly what you need
pip install "semhood[anthropic,local]"

分離された CLI インストールを希望しますか？ pipx を使うと、semhood とその依存関係をグローバル環境から分離できます。コマンドラインツールにおすすめです。

pipx install "semhood[local]"

インストールせずに試してみたいですか？ uv を使えば、PyPI から直接実行できます。

uvx --from "semhood[local]" semhood index .

必要条件 Python 3.11 以上。初回のインデックス作成時に埋め込みモデルがダウンロードされます（デフォルトの all-mpnet-base-v2 では約 420 MB）。モデルはキャッシュされます。

60秒で始める

設定ファイルも API キーもセットアップも不要です。semhood はデフォルトでローカルの埋め込みモデルを使ってオフラインで動作します。任意のプロジェクトに cd してインデックスを作成するだけです。

# 1. structural index — no LLM, free, no config needed
cd ~/code/your-project
semhood index .

# 2. search — pure retrieval, ~80 ms (a background daemon stays warm)
semhood search "how does the payment retry logic work?"

# 3. (optional) LLM enrichment — needs an Anthropic/OpenAI/OpenRouter/Ollama key
semhood enrich

# 4. (optional) full RAG with answer generation
semhood query "where is auth handled?"

最初のコマンドを実行すると、バックグラウンドのデーモンが自動的に起動し、埋め込みモデルを一度読み込んでウォーム状態に保ちます。そのため、後続の検索はどのターミナルやエディターからでも即座に実行できます。各プロジェクトには、リポジトリのルートをキーとして、~/.semhood/indexes/ 以下に専用のインデックスが自動的に作成されます。全体で共通の設定は ~/.semhood/config.yaml に保存されます（初回実行時に作成されます）。管理が必要なプロジェクトごとの設定ファイルはありません。

CLI コマンド

すべてのコマンドは現在のプロジェクト（cwd から最も近い git ルート）を対象にします。 --root /path/to/repo で対象を指定できます。これらはデーモンへの軽量なクライアントです。モデルの読み込みや config.yaml フラグは必要ありません。

MCP — AI エディターに接続する

このパッケージには、8 つのツールを公開する MCP サーバー（semhood-mcp）が含まれています。検索用が 5 つ、エージェントによる拡充用が 3 つです。

一度、グローバルに登録すれば、開いたすべてのプロジェクトで使えます。プロジェクトごとの設定は不要です。設定全体はこれだけです。エディターのユーザーレベルの MCP ファイルに追加してください。

{
  "mcpServers": {
    "semhood": {
      "command": "semhood-mcp"
    }
  }
}

設定はこれで完了です。config.yaml のパスも、プロジェクトごとの設定も必要ありません。サーバーは薄いプロキシとして動作し、各呼び出しを、エディターで現在開いているプロジェクト（最も近い Git ルート）を示すタグ付きで、起動済みのデーモンに転送します。ほとんどのエディターはワークスペースを作業ディレクトリとしてサーバーを起動するため、そのまま動作します。そうでない場合は、ルートを明示的に指定してください。

{ "command": "semhood-mcp", "args": ["--root", "${workspaceFolder}"] }

エディターを再起動すると、エージェントから semhood.search、semhood.find_symbol などを使えるようになります。デーモンはマシン全体で一度だけモデルを読み込むため、エディターやターミナルをいくつ開いていても、メモリ上のモデルは 1 つだけで、各呼び出しは約 80 ms で完了します。

エージェントに使いどころを教える（任意）

MCP サーバーはエージェントにツールを提供します。短いスキルを追加すると、grep や read より先にセマンティック検索を使うよう教えられます。使用するすべての AI エディターに、ユーザーレベルで一度インストールしてください。

semhood install-skill            # auto-detects installed editors
semhood install-skill -t all     # or force every supported target

対応対象：Claude Code（スキル）、Cursor と Windsurf（ルール）、Kiro（ステアリング）、Codex（AGENTS.md）。各エディター独自の規約に従ってユーザーレベルに書き込むため、ここにある他の設定と同様、一度設定すればすべてのプロジェクトに適用されます。いつでも再実行して、その場で更新できます。

トークン使用量にとって重要な理由

セマンティック検索がない場合、AI エージェントに 「メールアドレスの検証はどこで行っていますか？」 と尋ねると、grep -r email を実行して 200 件のヒットを得て、何十ものファイルを読み込みます。semhood を使えば、search("validate email") を呼び出して、順位付けされた 3 件のチャンクを JSON で取得し（約 500 トークン）、必要なものだけを読み込みます。

使用例 — 「OrderService は注文をどのように検証しますか？」

sample_project/ をインデックス化し、まさにその質問をしました。エージェントは 2 つの MCP ツールを呼び出して完了します。read_file も grep も使いません。

{
  "query": "how does OrderService validate an order before processing",
  "embedding_dim": 768,
  "results": [
    {
      "score": 0.455,
      "qualified_name": "OrderService::_validate",
      "file": "orders.py", "line_start": 115, "line_end": 124,
      "type": "method", "enrichment_state": "pending"
    },
    {
      "score": 0.397,
      "qualified_name": "OrderService",
      "file": "orders.py", "line_start": 49, "line_end": 124,
      "type": "class",
      "summary": "High-level orchestrator for placing and processing orders. Coordinates payment authorization (PaymentProcessor) and customer notification (NotificationService)."
    },
    {
      "score": 0.363,
      "qualified_name": "OrderService::place_order",
      "file": "orders.py", "line_start": 67, "line_end": 93,
      "summary": "Validate, charge, and confirm an order in one shot."
    }
  ]
}

{
  "found": true,
  "chunk": {
    "qualified_name": "OrderService::_validate",
    "file": "orders.py", "line_start": 115, "line_end": 124,
    "source": "def _validate(self, order: Order) -> None:\n    if order.is_empty():\n        raise ValueError(\"Order has no line items\")\n    if order.total_cents() < self.MIN_ORDER_CENTS:\n        raise ValueError(...)\n    if \"@\" not in order.customer_email:\n        raise ValueError(\"customer_email must be a valid email address\")",
    "calls": ["order.is_empty", "ValueError", "order.total_cents"],
    "called_by": [
      {"function": "place_order", "class_name": "OrderService", "file": "orders.py", "line": 67}
    ]
  }
}

grep してから読む方法（orders.py（3.5 KB）を開き、validate を検索し、呼び出しを確認するために place_order までたどる）と比べると、MCP を使う方法ではトークンをおよそ 40% に抑えられ、ファイル I/O も完全に省けます。

拡充する 2 つの方法

ステージ 2（description / developer_queries のベクトル化）には LLM が必要です。方法を選べます。

オプション A — 直接 API を使う

semhood が Claude / GPT / OpenRouter / Ollama を直接呼び出します。

semhood enrich

CI、バッチジョブ、AI エディターを使っていないユーザーに最適です。config.yaml で llm.provider と llm.<provider>.api_key を設定してください。

オプション B — AI エージェントに任せる

API キーは不要です。エディター内のエージェント（Cursor の Claude、Kiro、Cline、Continue など）が、MCP ツールを使って処理待ちのチャンクを順に処理し、要約を作成します。semhood 側の LLM コストはかかりません。 次のように指示するだけです。

「コードベースのインデックスを拡充して」

エージェントは list_pending_enrichments を使い、要約を書き込み、save_enrichment を実行して、enrichment_progress が処理待ちゼロを報告するまで繰り返します。すでに利用料金を支払っているモデルとサブスクリプションを使います。

拡充データを持ち運ぶ — 一度だけ費用を払い、共有し、モデル変更後も保持する

拡充（LLM が作成する要約と developer queries）は、semhood でトークンコストがかかる唯一の処理です。semhood は、そのテキストをリポジトリ内の .semhood/enrichment.jsonl に、各チャンクのコンテンツハッシュをキーとして保存します。ベクトルインデックス（~/.semhood/indexes/ に保存され、破棄可能です）とは別です。

.semhood/enrichment.jsonl を git にコミットしてください。 これにより、次のことができます。

• チーム間で共有する — チームメイトがクローンして semhood index を実行すると、ファイルから拡充データが復元され、ローカルで再びベクトル化されます。すでに拡充済みのコードに対する LLM トークンコストは ゼロ です。
• 埋め込みモデルの変更後も保持する — ローカルモデルから Voyage/OpenAI に切り替え、semhood index --reset を実行すると、拡充データが新しいベクトル空間に再度ベクトル化され、再拡充は不要 です。（これがなければ、モデルを変更するたびにすべての費用を再度支払う必要がありました。）
• ブランチの切り替えやリバート後も保持する — 古いレコードはコンテンツアドレス方式のキャッシュとして保持されるため、古いリビジョンをチェックアウトすると、その拡充データをすぐに再利用できます。

コンテンツアドレス方式なので、常に安全です。チャンクのコードが変更されるとハッシュが一致しなくなり、そのチャンクだけが再拡充されるため、古い要約が変更後のコードに紐付くことはありません。どのコードからも参照されなくなったレコードを削除するには、semhood compact を実行してください。このファイルにはテキストのみが含まれ、シークレットは含まれません。

.semhood/enrichment.jsonl   ← commit this (portable enrichment, ~text)
~/.semhood/indexes/<id>/    ← never committed (vectors, machine-local)

OpenRouter — 1 つのキーであらゆるモデルを利用

Anthropic、OpenAI、Google のアカウントを個別に管理したくない場合は、semhood の接続先を OpenRouter に設定してください。

llm:
  provider: "openrouter"
  openrouter:
    api_key: "${OPENROUTER_API_KEY}"
    model: "anthropic/claude-sonnet-4.6"   # or openai/gpt-5.5, anthropic/claude-opus-4.7, etc.

任意の対応モデルのスラッグを使用できます。semhood enrich と semhood query のコマンドはこれまでと同じです。

アーキテクチャ

チャンクごとに名前付きの高密度ベクトルを3つ使用します。code（常に使用）、description（エンリッチメント後）、developer_queries（エンリッチメント後）に加え、bm25 スパースベクトルを使用します。エンリッチメント前でも、code と BM25 のみで検索できます。

ステージ 1（semhood index）では、Tree-sitter でファイルを解析し、呼び出しグラフを構築して、ソースハッシュを計算し、ソースの生データを code ベクトルに埋め込み、Qdrant にアップサートします。LLM の呼び出しはありません。すべてのチャンクは pending 状態になります。

ステージ 2（semhood enrich）では、保留中のキューを LLM で処理し、各チャンクについて logic_summary と 5〜10 個の developer_queries を生成します。それらを description ベクトルと developer_queries ベクトルに埋め込み、テキストをポータブルな .semhood/enrichment.jsonl ストアにもミラーリングします。状態は fresh に切り替わります。簡単なチャンクには無料のテンプレートを使用し、テストはパターンに基づいてスキップします。

設定

semhood は ~/.semhood/config.yaml にある1つのグローバル設定を使用します（初回実行時にデフォルト設定で作成されます）。デーモンはすべてのプロジェクトでこの設定を読み込みます。$SEMHOOD_CONFIG を使って、明示的に指定したファイルを参照することもできます。環境変数の参照（${VAR}）は、~/.semhood/.env、ローカルの .env.semhood／.env、または実際の環境から解決されます。インデックスは ~/.semhood/indexes/<id>/ の下にプロジェクトのルートごとに1つずつ一元的に保存されるため、path を設定する必要はありません。

embeddings:
  provider: "local"            # local | voyage | openai | cohere
  local:
    model: "sentence-transformers/all-mpnet-base-v2"
  # voyage:                    # code-tuned, no local load — needs an API key
  #   api_key: "${VOYAGE_API_KEY}"
  #   model: "voyage-code-2"

llm:
  provider: "anthropic"
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"
    model: "claude-sonnet-4-6"

vector_db:
  provider: "qdrant"        # path is managed per-project by the daemon

enrichment:
  enabled: true
  version: 1
  llm_concurrency: 4
  skip_patterns: ["**/test_*.py", "**/*_test.go", "**/tests/**"]
  skip_trivial:
    enabled: true
    max_lines: 3

対応言語

トラブルシューティング

ステータス

レート制限が発生する場合は、enrichment.llm_concurrency を調整するか、エージェント駆動のエンリッチメントフローを使用してください。

コントリビューション

Issue と PR を歓迎します。

# Run tests
pytest

# Build a release
python -m build

対応できる項目については、未解決の Issue をご覧ください。