index_codebase

Index a project directory for semantic search

Overview

Walks a project directory, extracts semantic code chunks using AST analysis, embeds them locally, and stores them in a vector index. Subsequent calls skip unchanged files (incremental updates).

Parameters

Parameter	Type	Default	Description
path	string	required	Absolute path to the codebase root directory
force	boolean	false	Re-indexes all files even if unchanged. Required when switching embedding providers.
watch	boolean	false	Start a background file watcher that re-indexes changed files automatically. Local provider only.
provider	string	null	Embedding provider: "local" (default), "openai", "voyage", or "gemini".

Example

index_codebase("/path/to/myproject")
→ "Indexed 142 file(s), 1847 chunk(s) added (0 file(s) skipped, unchanged)"

Force a full rebuild:

index_codebase("/path/to/myproject", force=True)

Use a cloud embedding provider:

index_codebase("/path/to/myproject", provider="openai")

Provider lock

Once a project is indexed with a provider, re-indexing with a different provider requires force=True. This rebuilds the vector table with the correct embedding dimensions for the new provider.

index_codebase("/path/to/myproject", provider="voyage", force=True)

Live watch

watch=True starts a background watcher that detects file saves and re-indexes only changed files automatically. Only supported with the local provider — using watch=True with a cloud provider returns an error to prevent unbounded API costs.

index_codebase("/path/to/myproject", watch=True)

Use stop_watching to stop the watcher.

Notes

• Only re-indexes files whose mtime or size has changed since the last run
• Index is stored under ~/.vecgrep/<sha256-of-project-path>/lancedb/ with a merkle.json fingerprint file
• To also build the knowledge graph (for search_graph, graph_neighbors, hybrid_search), run index_graph after indexing