semhood

Stop grepping. Find the exact code your AI agent needs by intent, not keywords. semhood is an AST-aware semantic code search engine that retrieves code by what it does, complete with call-graph context and optional LLM enrichment.

Runs fully offline with zero API keys — or plug in cloud embeddings — Voyage's code-specialized models, or OpenAI's strong general-purpose (natural-language) embeddings — for higher-quality retrieval. Optional LLM enrichment adds a logic summary and developer queries to each chunk that you commit once and share — and every result ships with its call graph (what it calls + what calls it).

Why semhood · Install · Quickstart · MCP Setup · Architecture · Config · Troubleshooting

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

                                Search via CLI, HTTP, or MCP.

semhood indexes your codebase the way a developer thinks about it: every function, method, and class becomes a chunk, with its call graph, docstring, and signature attached. You search by intent ("how do we retry transient payment failures?") and get back the few chunks that actually answer the question.

Two stages: structural (always, free, ~seconds) and enrichment (optional, LLM or code agent, drains a pending queue). The index is queryable after stage 1; stage 2 just makes natural-language matches sharper.

The package ships an MCP server so Claude Desktop, Cursor, Cline, Continue, Kiro, Zed, and any other MCP-aware client can call semhood as a tool — your AI agent gets search, find_symbol, and get_chunk_context next to its built-in read_file and grep.

What makes semhood different

Most code search embeds your raw source and hopes a natural-language query lands near it. semhood adds two things plain vector search and grep can't:

🧠 Enrichment that thinks like a developer

An LLM reads each function and class and writes two artifacts, each stored as its own search vector:

• A logic summary — what the code actually does, in plain language. Not its name, not its signature — its behavior.
• Predicted developer questions — the real questions an engineer would ask to find this code: "how do we retry a failed payment?", "where are customer emails validated?"

This is the part that makes retrieval click. When you search with a question, you're matching against questions the code was pre-labeled to answer — so the right chunk wins even when it shares zero keywords with your query. You generate the enrichment once, commit it to git, and your whole team — and every AI agent — retrieves better for free. → Portable enrichment

Why enrichment matters: some code has no words to search. Plain semantic search only works when the source contains language close to your question. Plenty of important code doesn't — terse names, raw math, business rules. Consider a function like:

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

Ask "how do we calculate compound interest?" and plain vector search comes up empty — there's no "interest", no "compound", nothing in the source that means anything close to the question. Enrichment reads the code and generates:

{
  "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?"
  ]
}

Now your question matches a pre-written question that means the same thing, and _calc ranks first — despite sharing zero words with your query. The cryptic-but-critical functions are exactly the ones plain semantic search misses and enrichment rescues.

🕸️ Every result ships with its call graph

Each chunk knows what it calls and what calls it. So a result isn't just "here's the function" — it's the function plus its neighborhood. One get_chunk_context call returns the body, calls, and called_by together, so your AI agent gets the caller/callee context in the same response instead of opening files and tracing references by hand.

Features

• Retrieval-boosting enrichment — an LLM gives each chunk a plain-language logic summary + predicted developer questions, indexed as their own vectors so question-style queries hit the right code even with zero shared keywords. Written once, committed to git, shared with the team.
• Call graph included — each result knows what it calls and what calls it, so your agent gets the neighborhood, not just the function
• AST-aware chunking via Tree-sitter — every function, method, and class becomes a first-class searchable unit
• Hybrid retrieval — dense vectors (code, description, developer_queries) + BM25 sparse, all in one query
• Token-efficient for AI agents — replaces dozens of read_file + grep calls with one search
• MCP server out of the box — works with Claude Desktop, Cursor, Cline, Continue, Kiro, Zed
• 10 languages — Python, JavaScript, TypeScript, Java, Go, PHP, C#, Ruby, Rust, C++
• Free tier works — local embeddings + structural pipeline need zero API keys
• Incremental indexing — --changed re-indexes only what git diff touched

Install

# 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]"

Prefer an isolated CLI install? pipx keeps semhood and its deps out of your global environment — recommended for a command-line tool:

pipx install "semhood[local]"

Just want to try it without installing? With uv, run it straight from PyPI:

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

Requires Python 3.11+. First index downloads the embedding model (~420 MB for the default all-mpnet-base-v2) and caches it.

60-second quickstart

No config files, no API keys, no setup. semhood works offline with a local embedder by default. Just cd into any project and index it:

# 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?"

The first command auto-starts a background daemon that loads the embedding model once and keeps it warm — so every later search (from any terminal or your editor) is instant. Each project gets its own index automatically under ~/.semhood/indexes/, keyed by repo root. One global config lives at ~/.semhood/config.yaml (created on first run); there is no per-project config file to manage.

CLI commands