semhood

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

All commands act on the current project (nearest git root of your cwd).

Override with --root /path/to/repo. They're thin clients to the daemon — no

model loading, no config.yaml flag.

---

MCP — wire it into your AI editor

The package ships an MCP server (semhood-mcp) that exposes eight tools — five for search, three for agent-driven enrichment:

Register it once, globally — it then works in every project you open, with no per-project setup. This is the entire config — drop it into your editor's *user-level* MCP file:

{

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

Where that file lives, per editor (click to expand)

A few clients use a slightly different shape — e.g. VS Code's native MCP uses a

top-level "servers" key instead of "mcpServers". If yours differs, keep