Repolode
Submit
boyter

boyter/cs

A CLI code search tool that parses code structure and ranks results by relevance, with no index required.

Open-source alternative to:Sourcegraph

View on GitHub
Stars
1,080
Forks
23
Open issues
2
Last commit
3 days ago

What is it?

cs (codespelunker) is a command-line code search tool written in Go. It parses each matching file on the fly to tell code, comments, and strings apart, then ranks results by BM25 relevance with structural weighting, rather than listing every textual occurrence. Because nothing is pre-indexed, it can be pointed at any directory and searched immediately.

Beyond plain search, it supports structural filters such as --only-code, --only-comments, --only-strings, --only-declarations, and --only-usages. A complexity-based "gravity" setting lets implementation files outrank interfaces and config files, and ranking profiles bundle several tuning parameters into presets. Boolean operators, quoted phrases, regular expressions, and fuzzy matching are supported in queries.

The same engine runs as an interactive TUI, an HTTP search server with optional syntax highlighting, or an MCP server that lets LLM tools such as Claude Desktop and Claude Code search a codebase. A --git-sync option periodically pulls repositories in a search directory to keep results current.

Key features

  • 01Structure-aware matching that distinguishes code, comments, and string literals
  • 02BM25 relevance ranking with complexity-based gravity and file-location boosting
  • 03Declaration and usage filters for jumping to definitions or call sites
  • 04Boolean queries, quoted phrases, regex, and fuzzy matching
  • 05Console, TUI, HTTP server, and MCP interfaces
  • 06Periodic git pull for repositories in a search directory

Use cases

  • Finding the real implementation of a function instead of its interface, tests, or comments
  • Searching only TODO/FIXME comments or error message strings across a project
  • Giving an LLM agent a ranked code search tool through MCP
  • Searching a directory of cloned repositories without maintaining a search server

Quick start

  1. 1

    Install via Go (requires Go 1.25.2 or newer)

    go install github.com/boyter/cs/v3@latest
  2. 2

    Run a search from any directory

    cs "authenticate" --gravity=brain

Things to know

  • Requires Go 1.25.2 or newer for the go install route; other installs need the releases page binaries.
  • No index, so every search scans matching files on the fly and is slower than ripgrep for plain text matching.

Topics

#code-search#cli#command-line-tool#developer-tools#bm25#mcp#tui#golang#code#search

FAQ

What is cs?
A CLI code search tool that parses code structure and ranks results by relevance, with no index required. cs (codespelunker) is a command-line code search tool written in Go. It parses each matching file on the fly to tell code, comments, and strings apart, then ranks results by BM25 relevance with structural weighting, rather than listing every textual occurrence. Because nothing is pre-indexed, it can be pointed at any directory and searched immediately.
Is cs free to use? What license does it have?
cs is open source under the MIT license. Check the license terms before using it in commercial products.
Is cs still maintained?
Actively maintained. The last commit to cs was on Oct 20, 2026.
What can I use cs for?
Finding the real implementation of a function instead of its interface, tests, or comments Searching only TODO/FIXME comments or error message strings across a project Giving an LLM agent a ranked code search tool through MCP Searching a directory of cloned repositories without maintaining a search server
How do I install cs?
Install via Go (requires Go 1.25.2 or newer): go install github.com/boyter/cs/v3@latest Run a search from any directory: cs "authenticate" --gravity=brain
Where can I get cs?
The source code and installation instructions are on GitHub: https://github.com/boyter/cs

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects