combfind 0.1.8

Queryable concept map of a codebase for LLM coding agents

combfind

Give an AI agent a codebase. combfind tells it where to look.

combfind builds a local index of a repository so an agent can find the right files and functions for a task with a plain-text query, without reading the entire codebase.

Install

pip3 install "combfind[llm]" \
  --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu

Or with uv:

uv pip install "combfind[llm]" \
  --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu

Download a model (one-time, ~2 GB):

combfind download-model

Usage

# Index a repository (requires a local LLM model)
combfind init /path/to/repo --db repo.db

# Query it
combfind query "how does authentication work" --db repo.db
combfind query "where are database migrations" --db repo.db --format json

Query output (JSON)

[
  {
    "rank": 1,
    "concept": "Token Refresh",
    "role": "implementation",
    "score": 0.87,
    "files": [{"path": "auth/service.py", "start_line": 42, "end_line": 91}],
    "symbols": ["AuthService.refresh", "AuthService.validate"],
    "why_relevant": "Handles session token validation and refresh logic.",
    "sibling_implementations": []
  }
]

Init options

Flag	Default	Description
--db	<repo_path>/.combfind.db	Output path
--llm-model	auto-detected	Path to a GGUF model file
--exclude-paths	-	Paths to skip relative to repo root (repeatable)
--exclude-regex	-	Regex matched against file paths to skip

Query options

Flag	Default	Description
--db	.combfind.db	Database to query
--top-k	5	Number of results to return
--format	text	Output format: text or json

Environment variables

Variable	Default	Description
COMBFIND_LOG_LEVEL	info	Log verbosity: debug, info, warning, error

Supported languages

Python, Go. More languages can be added via tree-sitter grammars.