Exploring Codebases
exploring-codebases
Semantic search for codebases. Locates matches with ripgrep and expands them into full AST nodes (functions/classes) using tree-sitter. Returns complete, syntactically valid code blocks rather than fragmented lines. Use when looking for specific implementations, examples, or references where full...
SKILL.md
Full skill instructions
Exploring Codebases
Hybrid search tool that combines the speed of ripgrep with the structural awareness of tree-sitter. It finds matches and returns the entire function or class containing the match, de-duplicating results semantically.
Progressive Disclosure
By default, returns signatures only (docstrings + declarations without function bodies), reducing token usage by 10-20×. Use --expand-full to get complete implementations when needed.
Installation
uv venv /home/claude/.venv
uv pip install tree-sitter-language-pack --python /home/claude/.venv/bin/python
Usage
# Default: signatures only (efficient)
/home/claude/.venv/bin/python /mnt/skills/user/exploring-codebases/scripts/search.py "query" /path/to/repo
# Full implementations
/home/claude/.venv/bin/python /mnt/skills/user/exploring-codebases/scripts/search.py "query" /path/to/repo --expand-full
Options
--glob pattern: Filter files (e.g.,*.py,*.ts)--expand-full: Return full implementations instead of signatures--json: Output JSON for machine processing (default is Markdown)
Examples
Find class signatures:
/home/claude/.venv/bin/python /mnt/skills/user/exploring-codebases/scripts/search.py "class User" /path/to/repo
Output:
class User:
"""User account model."""
...
Find full method implementation:
/home/claude/.venv/bin/python /mnt/skills/user/exploring-codebases/scripts/search.py "def validate" /path/to/repo --expand-full
Find usage of process_data in Python files:
/home/claude/.venv/bin/python /mnt/skills/user/exploring-codebases/scripts/search.py "process_data" /path/to/repo --glob "*.py"