boyter/cs

Codespelunker (cs) sits between raw grep and a heavyweight indexed code-search service. It parses files on demand, distinguishes code from comments and strings, detects declarations and usages, ranks results with BM25 and configurable signals, and can boost complex implementation files over interfaces or tests. Console, TUI, HTTP, and MCP modes make the same engine useful for people and agents, while profiles, boolean queries, deduplication, language filters, and zero-index operation keep setup simple.

The ranking model is the project’s value and the area that needs the clearest evidence. Public relevance datasets, latency measurements across repository sizes, and comparisons with ripgrep, Zoekt, and Sourcegraph would help users understand the tradeoffs. Complexity should remain an optional signal because the most relevant implementation is not always the most complex one. --git-sync also deserves explicit authentication, merge, and untrusted-repository guidance. cs is best for developers or local agents that need more relevant code search without maintaining an index; teams searching huge, constantly changing monorepos should benchmark query latency and ranking quality on their own workload.

I really like what cs is trying to be. It is not just another grep wrapper or a slower ripgrep; it has a clear point of view: searching code should care about where a match appears, not just whether the bytes match. The ability to rank code matches differently from comments or strings, jump toward declarations or usages, use BM25-style relevance, run without an index, and still offer CLI, TUI, HTTP, and MCP modes makes the project feel genuinely useful for people working in unfamiliar codebases.

The README does a strong job selling that idea. The examples are practical, especially things like finding real implementations instead of interfaces, searching only comments for TODO-style work, or using git-sync to keep a local set of repositories searchable. The project also has good open-source signals: recent releases, tests for important behavior, a contributing guide, a code of conduct, release automation, and very little issue/PR backlog. It feels maintained rather than abandoned.

The main thing I would improve is onboarding. The README has a lot of good information, but it is a bit dense once you get past the pitch. A short “try these three commands first” section would make it easier for new users to feel the value immediately. I would also add a small architecture or ranking document that explains, in plain language, how query parsing, structural detection, ranking, snippets, and output modes fit together. Since “understands code structure” is central to the project, making that promise more precise would help users trust the tool and help contributors avoid changing ranking behavior accidentally.

Overall, this is a thoughtful, well-maintained developer tool with a real reason to exist. The best next step is not a big rewrite, but clearer first-run guidance and a little more transparency around how the ranking works.