Skip to content
Skills Library
Programming · Analysis

searching-codebases

/searching-codebases

Binding-resolved Python symbol queries via pyright — every true caller (--refs), the real definition (--def), or an inferred signature (--hover) of a .py symbol, excluding the same-named false positives text search cannot tell apart. Use when a task needs ALL callers or users of a named Python symbol and grep would over-match. Python only, and only for the caller/definition question: measured 2026-07-04 on real issue-localization tasks, plain ripgrep tied or beat the semantic and indexed-regex tiers at 4-60x less wall-clock, so those tiers survive below without being a default.

Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
15
Scripts
12
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 12 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/code_rag.py, scripts/context.py, scripts/lsp_refs.py, scripts/ngram_index.py, scripts/resolve.py, scripts/search.py, scripts/sparse_ngrams.py, tests/fixture/pkg/__init__.py

What it does and when to use it

Binding-resolved Python symbol queries via pyright — every true caller (--refs), the real definition (--def), or an inferred signature (--hover) of a .py symbol, excluding the same-named false positives text search cannot tell apart. Use when a task needs ALL callers or users of a named Python symbol and grep would over-match. Python only, and only for the caller/definition question: measured 2026-07-04 on real issue-localization tasks, plain ripgrep tied or beat the semantic and indexed-regex tiers at 4-60x less wall-clock, so those tiers survive below without being a default.

Original author description

Binding-resolved Python symbol queries via pyright — every true caller (--refs), the real definition (--def), or an inferred signature (--hover) of a .py symbol, excluding the same-named false positives text search cannot tell apart. Use when a task needs ALL callers or users of a named Python symbol and grep would over-match. Python only, and only for the caller/definition question: measured 2026-07-04 on real issue-localization tasks, plain ripgrep tied or beat the semantic and indexed-regex tiers at 4-60x less wall-clock, so those tiers survive below without being a default.

How it works

  1. When NOT to use this skill
  2. Prerequisites
  3. Primary Command
  4. Search Modes
  5. Options
  6. How It Works
  7. Mixed Queries
  8. Dependencies
  9. When to Use — narrow, by design
  10. When NOT to Use — which is most of the time
Original SKILL.md headings · 182 lines, 1,042 words
SKILL.md preview
---
name: searching-codebases
description: >-
  Binding-resolved Python symbol queries via pyright — every true caller
  (--refs), the real definition (--def), or an inferred signature (--hover)
  of a .py symbol, excluding the same-named false positives text search
  cannot tell apart. Use when a task needs ALL callers or users of a named
  Python symbol and grep would over-match. Python only, and only for the
  caller/definition question: measured 2026-07-04 on real issue-localization
  tasks, plain ripgrep tied or beat the semantic and indexed-regex tiers at
  4-60x less wall-clock, so those tiers survive below without being a
  default.
metadata:
  version: 2.5.0
---

# Searching Codebases

Find code in any codebase by pattern or concept. One entry point, two
search strategies, automatic routing.

## When NOT to use this skill

Python callers and definitions only. Every other code question is cheaper
elsewhere, and the measurement below is why this skill is edge-case-only.

| Situation | Use |
|---|---|
| What symbols does this file contain? | tree-sitting |
| Where is X defined, so I can read it? | tree-sitting |
| Any structure question, any language | tree-sitting |
| A literal string or regex | plain ripgrep |
| Which files are most about a concept? | bm25 |
| First look at an unfamiliar repo | exploring-codebases |

Non-Python code has no pyright binding resolution to offer, so there is no
version of this skill that applies to it.

## Prerequisites

```bash
uv tool install ripgrep
```

tree-sitting installs automatically when needed — for `--expand` context
expansion and for the binding-resolved `--refs`/`--def`/`--hover` tier, which
uses it to resolve symbol positions. Only the bare `tree-sitter` package is
fetched; the language grammars ship bundled.

## Primary Command

```bash
SKILL_DIR=/mnt/skills/user/searching-codebases

python3 $SKILL_DIR/scripts/search.py SOURCE "query1" ["query2" ...] [OPTIONS]
```

SOURCE is any of:
- Local directory path
- GitHub URL (downloads tarball automatically)
- `uploads` (uses `/mnt/user-data/uploads/`)
- `project` (uses `/mnt/project/`)
- Path to a `.zip` or `.tar.gz` archive

## Search Modes

**Regex mode** (patterns, identifiers, literal text):
```bash
python3 $SKILL_DIR/scripts/search.py ./repo "def handle_error"
python3 $SKILL_DIR/scripts/search.py ./repo "class.*Exception" --regex
python3 $SKILL_DIR/scripts/search.py ./repo "TODO|FIXME|HACK"
```

**Semantic mode** (concepts, natural language):
```bash
python3 $SKILL_DIR/scripts/search.py ./repo "retry logic with backoff" --semantic
python3 $SKILL_DIR/scripts/search.py ./repo "authentication flow"
python3 $SKILL_DIR/scripts/search.py ./repo "error handling strategy"
```

Auto-detection: short queries and code-like tokens → regex. Multi-word
natural language → semantic. Override with `--regex` or `--semantic`.

**Binding-resolved mode** (Python only — pyright via the `python-lsp` skill):
```bash
python3 $SKILL_DIR/scripts/search.py ./repo --refs SYMBOL    # find all real uses
python3 $SKILL_DIR/scripts/search.py ./repo --def SYMBOL     # go-to-definition
python3 $SKILL_DIR/scripts/search.py ./repo --hover SYMBOL   # inferred type/signature
```

Regex mode matches *text*, so a cross-reference for a function false-positives
on shadowed and same-named-but-unrelated symbols. `--refs` is **binding-resolved**:
pyright excludes the unrelated same-named symbol and follows imports. Use it when
you need a true "find all callers/users" for a `.py` symbol, not a text grep.

The tier is engaged **lazily** — pyright's index cost is paid only when you ask
for `--refs`/`--def`/`--hover`, never on ordinary searches. It is **Python-only**;
for non-`.py` sources, or when pyright/node is unavailable, it prints a one-line
degradation note and falls back to the regex text path. Each takes a single bare
symbol name and is mutually exclusive with the other two and with text queries.

## Options

- `--regex` / `--semantic`: Force search mode
- `--refs SYMBOL` / `--def SYMBOL` / `--hover SYMBOL`: Binding-resolved Python
  queries via pyright (see Binding-resolved mode above)
- `--expand`: Return full function bodies via tree-sitting AST context
- `--benchmark`: Compare indexed regex vs brute-force ripgrep
- `--branch NAME`: Git branch for GitHub URLs (default: main)
- `--skip DIRS`: Comma-separated directories to skip
- `--json`: Machine-readable output
- `-v`: Show index stats and query routing decisions

## How It Works

**Regex search** builds a sparse n-gram inverted index over all files.
Queries are decomposed into literal fragments, looked up in the index
to identify candidate files (typically 90-99% reduction), then verified
with ripgrep. Frequency-weighted n-grams make rare character sequences
more selective.

**Semantic search** builds a TF-IDF index over code chunks (functions,
classes, structural entries). Queries are ranked by cosine similarity.

**Context expansion** (`--expand`) uses tree-sitting's AST cache to
identify function/class boundaries, returning complete structural units
rather than line fragments. On first use, tree-sitting scans the repo
(~700ms for 250 files); subsequent expansions are sub-millisecond.

**Small codebases** (< 20 files) skip indexing entirely — direct ripgrep is
faster when there's nothing to narrow.

## Mixed Queries

Multiple queries can use different modes in a single invocation. Each query
is auto-routed independently, and indexes are built once per mode:

```bash
python3 $SKILL_DIR/scripts/search.py ./repo \
  "class.*Error" \
  "error recovery strategy" \
  "def retry"
```

## Dependencies

- **tree-sitting**: Provides AST context expansion for `--expand` *and* the
  symbol→position resolution that seeds the binding-resolved tier
  (`--refs`/`--def`/`--hover`). Auto-installs the bare `tree-sitter` package
  when either is used (grammars are bundled). Regex and semantic search work
  without it.
- **ripgrep**: Required for regex verification. Install via `uv tool install ripgrep`.
- **scikit-learn**: Required for semantic mode. Installs automatically.
- **python-lsp**: Provides the binding-resolved tier (`--refs`/`--def`/`--hover`).
  Self-bootstraps pyright on first use and requires system `node` (v18+). Not
  required — without it those flags degrade to the regex text path.

## When to Use — narrow, by design

The ONE recommended use: **binding-resolved Python symbol queries**.

- "find all callers of `X`" / "where is `X` really defined" for a `.py`
  symbol, when same-named-but-unrelated symbols would pollute a text grep.
  Empirical basis: `rg get` on psf/requests returned 232 hits, 224 of them
  false; `--refs get` excluded all 224 (2026-06-15).

## When NOT to Use — which is most of the time

Everything else. Measured head-to-head on real issue-localization tasks
(7 scikit-learn issues with merged fix-PRs, gold = PR diff files,
2026-07-04, replicating the file-discovery metric of arXiv:2602.11988):

- **Literal tokens / identifiers**: naive `rg -l` tied or beat the indexed
  tier on recall@10 in every instance, at 0.4s vs 25s.
- **Concept / natural-language search**: the TF-IDF semantic tier never
  beat identifier grep — not even on identifier-poor issues, which are
  themselves rare (~0.3% of merged-PR traffic in the sample).
- **First encounter / "what is this repo"**: use exploring-codebases.
- **Repos under ~20 files**: read them.

The self-test before invoking: would plain `rg` return the same answer?
If yes, use rg. The indexed-regex and semantic tiers are retained for
completeness and for corpora where they may yet earn their cost (very
large repos, non-code document collections), but they carry the burden
of proof.

## Files

- `scripts/search.py` — Entry point, query routing, output formatting
- `scripts/resolve.py` — Input source resolution (GitHub, uploads, archives)
- `scripts/context.py` — tree-sitting-based AST context expansion
- `scripts/ngram_index.py` — Sparse n-gram inverted index, regex decomposition
- `scripts/sparse_ngrams.py` — Core n-gram algorithms, frequency weights
- `scripts/code_rag.py` — TF-IDF semantic search over code chunks
- `scripts/lsp_refs.py` — Binding-resolved Python tier: symbol→position
  resolution (tree-sitting), pyright queries (python-lsp), soft fallback
Files in this package (15)
  • CHANGELOG.md 4 KB
  • README.md 2 KB
  • SKILL.md 8 KB
  • scripts/code_rag.py 20 KB
  • scripts/context.py 6 KB
  • scripts/lsp_refs.py 18 KB
  • scripts/ngram_index.py 21 KB
  • scripts/resolve.py 4 KB
  • scripts/search.py 13 KB
  • scripts/sparse_ngrams.py 6 KB
  • tests/test_lsp_refs.py 5 KB
  • tests/fixture/pkg/__init__.py 1 KB
  • tests/fixture/pkg/models.py 1 KB
  • tests/fixture/pkg/other.py 1 KB
  • tests/fixture/pkg/service.py 1 KB

Versions

The database has no other skills named searching-codebases.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version c92376e7b9a4 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100python-lsp
    Semantic Python code queries via a stdio LSP client driving pyright-langserver. Provides binding-resolved go-to-definition, find-references, hover types, type diagnostics, file symbol outlines, and project-wide symbol search — name resolution and type inference that tree-sitter…
  • 100python-lsp
    Use this skill whenever Claude needs semantic intelligence on Python source — type errors, import resolution, go-to-definition, find-references, or hover type information. Trigger on: "Python LSP", "pyright", "type error", "find references", "who calls this function", "where is…
  • 100basemind-code-search
    Find where code is defined and used without reading files — symbol search, file outlines, references, callers, call graphs, implementations, dependents, and indexed regex over content. Reach for it whenever the user asks "where is X defined", "what calls Y", "what implements Z",…
  • 80Navigating Codebases with CodeGraph
    Query a pre-indexed knowledge graph of a codebase (symbols, call graphs, dependencies, impact) instead of scanning files with grep/glob/Read. Use when exploring an unfamiliar codebase, tracing who calls or is called by a function, assessing the blast radius of a change, finding…
  • 100code-query
    Local source-code lookup; definitions/snippets only. USE FOR: definitions, callers/refs, requirement/test ID traces, symbol/regex search, code Q&A. PREFER OVER read_file, grep_search, and ripgrep for source files; fall back to grep only if hits are empty or unrelated. DO NOT USE…
  • 95mgrep-code-search
    Semantic code search using mgrep for efficient codebase exploration. This skill should be used when searching or exploring codebases with more than 30 non-gitignored files and/or nested directory structures. It provides natural language semantic search that complements…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.