boyter/cs

What it solves

cs (codespelunker) is a CLI tool designed to solve the problem of noise in code search. Unlike traditional text-based search tools like grep or ripgrep, which treat code as plain text, cs understands the structure of code to rank results by relevance, helping developers find actual implementations rather than just every occurrence of a keyword in comments or config files.

How it works

The tool performs lexical analysis on the fly without requiring a pre-built index. It parses files to distinguish between code, strings, and comments, and uses a weighted BM25 relevance scoring algorithm. It further refines ranking using "complexity gravity," which uses cyclomatic complexity to boost files containing core logic over simple boilerplate or interfaces.

Who it’s for

Developers and AI agents who need to perform structured, relevance-ranked code search across one or more repositories without the overhead of maintaining a search index.

Highlights

• Structural Awareness: Filters results to only show code, comments, strings, or declarations (e.g., func, class) and usages.
• Complexity Gravity: Boosts complex implementation files over simple interfaces or configuration files using cyclomatic complexity.
• No Indexing: Provides search-engine quality ranking on the fly, capable of searching the Linux kernel source in under 3 seconds on modern hardware.
• Multiple Interfaces: Supports a standard CLI, a TUI, an HTTP server, and an MCP (Model Context Protocol) server for LLM integration.
• Git Sync: Automatically keeps search targets up to date by periodically running git pull on discovered repositories.
• Smart Ranking: Uses BM25 scoring, file-location boosting, and automatic test-file dampening.