codespelunker CLI
Source search ranks matches using code structure and gives agents relevant snippets without a separate search index.
- 1,080 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The agent reads user-accessible source files; enabled Git synchronization updates local clones.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/codespelunkerDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent reads user-accessible source files; enabled Git synchronization updates local clones.
This is third-party code. Review the repository files before installing.
What it does
codespelunker searches project files and ranks matches by relevance. An agent can separate code from comments, find declarations or usages, and receive snippets with file paths and locations. Search works on current files without a prebuilt index. Console output, an interactive terminal view, HTTP and MCP interfaces are available. MCP exposes search and file reading, while ranking profiles favor focused implementation results or a broader set including tests.
Who it is for. Developers exploring an unfamiliar codebase who need to show an agent implementations and surrounding lines.
Good fit when
- A function name appears in code and documentation but the agent needs its implementation.
- An error investigation needs string literals containing a message.
- A new project must be explored without maintaining a search index.
- MCP source access should be restricted to a single directory.
Not a fit when
- You want automatic syntax-aware rewrites of matches.
- The output must contain a complete cross-project dependency graph.
- Ranking must prove that a matched implementation is correct.
Example request
Find the authentication implementation, exclude comments and show the most relevant files with code locations.Limitations
Installation through Go requires version 1.25.2 or newer; prebuilt binaries are a separate option. Declaration detection covers the listed languages, while other matches are treated as usages ranked by text relevance. In MCP mode, `--dir` sets a default directory only; use `--mcp-lock-dir` to enforce a read boundary. Optional Git synchronization performs pulls and changes local clones, so enable it only for approved working directories.
How to disable. Stop cs or remove its MCP client entry. Review any changes fetched through optional Git synchronization separately.
FAQ
Do I need to build an index first?
No. codespelunker reads current files for each query, so you can search a project directory immediately.
How do I search comments only?
Use `--only-comments`; code and strings have separate filters.
How do I include more tests?
Choose the `broad` profile, which includes tests at full weight.
What does an agent receive?
File names, match locations, snippets and relevance scores.
Why did a search leave the project directory?
MCP `--dir` alone does not restrict other paths. Enable `--mcp-lock-dir`.
Discussion
No questions or reviews yet.
Related
CLI toolsA structural code search MCP server for agents: finds the right file by query intent and runs locally
Fast semantic code search for agents: returns the exact snippets instead of reading whole files and spends far fewer tokens
The MCP server finds definitions and meaningful code fragments through a local index with vector and full-text search.
An MCP server that indexes a local repository with tree-sitter and gives the agent code search, file lookup and a structure summary of a file
An MCP server that indexes code with tree-sitter and returns individual functions and classes to the agent instead of whole files
A local codebase index for agents: hybrid search, dependency graphs and change impact analysis
README in short
Boolean expressions, regular expressions and fuzzy search are supported. Unknown MCP parameters produce an error.