code-search

## Repo discovery and ref resolution If you don't know which repo or ref (branch, tag, or version) to search, use your `repo-discovery` or `ref-resolution` skills first. ## Choosing the right tool ### `code.search` - BM25 keyword/concept search Use when you know *what* you're looking for but not *where*: - Concept or feature names ("circuit breaker", "token refresh", "shard allocation") - Natural-language descriptions of behavior - When exact spelling is uncertain (BM25 scores partial matches) Returns the top-N highest-scoring lines. Default n=10; increase to 25-50 for broader coverage. Results are ranked by relevance, not by file or line order. ### `code.grep` - regex search Use when you know the exact identifier or pattern: - Symbol definitions: class names, function names, constants, config keys - Import statements, annotation usages, string literals - Structural patterns (`public.*interface.*Service`, `@Override`) Returns all matching lines up to n. Default n=100; lower for focused lookups, raise if you expect many matches. Results are in file/line order. ### `files.ls` and `files.tree` - file and directory listings Use to orient yourself or confirm a path before reading: - Explore an unfamiliar repo's top-level structure - Find which subdirectory contains a feature (e.g. `src/main/java/org/elasticsearch/*/`) - Verify a file path exists before passing it to cat/head/grep Supports `*` (one path segment) and `**` (recursive) glob patterns. A bare `*` lists the top level. ### `files.cat` - full file contents Use for small, complete files where you need all the context: - Config files, build descriptors, short modules - Avoid on large source files - use grep/search with a narrow `file_path` instead Returns the entire file; no line limit. ### `files.head` - first N lines of a file Use when the top of the file is sufficient: - Package/module declarations, imports, class-level structure - File headers Default n=10; increase for longer preambles. ### `files.tail` - last N lines of a file Use when the bottom of the file is what matters: - Closing blocks, trailing configuration entries Default n=10. ### `files.wc` - count lines in file(s) Use to verify file sizes before deciding how to read files: - Avoid using `files.cat` on large files. Prefer `files.head`, `files.tail`, or `files.read_lines` to save tokens. - Prefer using l=true to count just the lines (not bytes, words, etc). ## Iterating toward an answer **Pattern 1 - concept → file → definition:** 1. `code.search` on the concept to identify candidate files 2. `files.ls` on a promising directory to confirm the layout 3. `code.grep` with a specific symbol pattern (e.g. `.*class CircuitBreaker.*`) to find the definition 4. `files.cat` or `files.head` for surrounding context **Pattern 2 - known symbol → definition:** 1. `code.grep` with an anchored regex scoped to `**` or a known subdirectory 2. If context is needed beyond the match lines, `files.cat` the file or widen the grep pattern **Pattern 3 - explore unfamiliar repo:** 1. `files.ls` at `*` to see the top-level structure 2. `files.ls` into the relevant subdirectory 3. `files.head` on key files (entry points, primary config) 4. `code.search` or `code.grep` to locate the specific feature ## Narrowing with `file_path` All content tools accept a `file_path` glob. Narrowing it cuts noise and speeds results: - `**/*.java` - all Java files - `src/main/**` - source tree only, excluding tests - `src/main/java/org/elasticsearch/index/**` - one subsystem - `config/elasticsearch.yml` - a specific file (exact match) A bare `*` matches a single path segment, so it lists only top-level files (no `/` in the path). Use `**` to recurse. ## Reading for citation When you read to cite a specific line or range, follow each tool's own citation guidance in its description, and see the `code-citations` skill for the full rules: - `code.grep` / `code.search` return one row per line, each with an authoritative `line.number` - cite single lines and never merge separate rows into a range. - `files.cat` / `files.head` / `files.tail` / `files.read_lines` prefix each returned line with its 1-indexed number by default (grep -n style, `<line>:<content>`) - read the number off the first and last lines to cite a range. Pass `show_line_numbers=false` when you want raw, unprefixed text. - Never derive a line position by counting lines inside returned content - read it from the per-line prefix. ## Parallel calls When two searches are independent, issue them in the same turn. For example, grep for a class definition and search for its concept simultaneously, then synthesize the results.