Codebase indexing

Codebase indexing lets Hull search your project by meaning rather than exact text. Ask about "where we validate passwords" and Hull can find the right code even if it never uses those words.

When indexing is on, Hull gets a semantic_search tool alongside its usual grep and glob. It uses it on its own when a search by meaning helps.

How it worksCopy Anchor Link

1. Hull parses your files locally with Tree-sitter and splits them into blocks such as functions, classes and methods. Markdown has its own parser, and other files fall back to line-based chunks.
2. Each block is turned into an embedding by the embedding provider you choose.
3. The embeddings are stored in a vector store: LanceDB on your machine, or a Qdrant server.
4. When Hull searches, your query is embedded the same way and the closest matches come back with their file paths, line ranges and similarity scores.

Hull watches your files and re-indexes only what changed, including after you switch branches.

Set it upCopy Anchor Link

Configure it in hull.jsoncCopy Anchor Link

All settings live under indexing:

{
  "indexing": {
    "enabled": true,
    "provider": "voyage",
    "model": "voyage-code-3",      // optional, provider default if omitted
    "dimension": 1024,             // optional, detected from the model if omitted
    "vectorStore": "lancedb",
    "voyage": { "apiKey": "pa-..." },
    "lancedb": {},
    "searchMinScore": 0.4,
    "searchMaxResults": 50,
    "embeddingBatchSize": 60,
    "scannerMaxBatchRetries": 3
  }
}

Embedding providersCopy Anchor Link

For Ollama, nomic-embed-text is a good balance of speed and quality, and mxbai-embed-large gives higher quality at a cost in speed.

Vector storesCopy Anchor Link

• LanceDB (lancedb, the default) is embedded and file-based, with no server to run. Data goes in Hull's data directory unless you set directory.
• Qdrant (qdrant, settings url and apiKey) suits larger codebases and shared servers.

To run Qdrant locally:

docker run -p 6333:6333 qdrant/qdrant

For production, use Qdrant Cloud or host it yourself, and turn on authentication.

TuningCopy Anchor Link

What gets indexedCopy Anchor Link

• Code is split into blocks of up to about 1,000 characters. Large functions are split.
• Files over 1 MB, binary files and images are skipped.
• .git, dependency folders such as node_modules, and anything matched by .gitignore or .hullcodeignore are skipped.

PrivacyCopy Anchor Link

• Parsing happens on your machine. Only the code blocks being embedded, and your search queries, are sent to your embedding provider.
• Provider API keys are stored in your hull.jsonc. Treat that file as a secret in shared environments.
• Ollama with LanceDB keeps everything local.

TroubleshootingCopy Anchor Link

Status stays on Disabled. Check that indexing is enabled (globally or for the project), that your provider has all required credentials, and that your Qdrant server is reachable if you use one.

Errors about n_ubatch or GGML_ASSERT with Ollama or llama.cpp. Set the batch size (-b) and micro-batch size (-ub) to the same value for embedding models and restart the server. For Ollama, set num_batch to match.

Rate-limit or batch errors. Lower embeddingBatchSize.