Cheapest way to find every place a pattern occurs. Prefer this over Glob-based path hunting and over Grep when you only need file + line numbers (no previews). Returns an array of {path, line} objects — one per match, no limit.

Use this for: enumerating locations before deciding which files to Read; counting affected sites; listing all hits of a pattern without paying for previews. Supports lang, file, glob, exclude filters.

Example: pattern: "CourtCase" → [{"path": "app/Models/CourtCase.php", "line": 15}, {"path": "app/Http/Controllers/CourtController.php", "line": 42}]. On "Index not found" / "stale" error, call index_project, then retry.

Count-only statistics for a pattern. Prefer this over piping grep -c / wc -l / rg --count — returns total occurrences and file count in one call without loading any content.

Use this for: "how many times is X used?"; impact checks before refactoring; validating search scope. Returns {total, files, pattern}. Supports all filters (lang, file, glob, exclude, symbols, kind).

Example: {"total": 87, "files": 12, "pattern": "CourtCase"}. On "Index not found" / "stale" error, call index_project, then retry.

Default code search across the whole codebase. Prefer this over Grep / grep -rn / Glob for any pattern made of letters, digits, underscores, or hyphens — one call returns every occurrence with file paths, line numbers, and code previews. Use this for: finding where a pattern occurs; listing all usages of a function/class/variable; finding a symbol's definition (with symbols: true); getting line numbers + previews in a single call.

Modes: full-text by default (definitions + usages); symbols: true returns definitions only; mode: "count" returns just {count, pattern} to check cardinality before paginating. For patterns containing special characters (->, ::, (), [], .*+?\|^$), use search_regex instead.

Result shape is columnar: {columns, rows} — each row aligns positionally to columns (path, language, start_line, end_line, preview; then kind/symbol/context when present). Set env REFLEX_MCP_COLUMNAR=0 for the legacy results[] shape.

Pagination: if response.pagination.has_more is true, fetch the next page with the offset parameter. On "Index not found" / "stale" error, call index_project, then retry.

Regex code search across the whole codebase. Prefer this over rg / grep -E / grep -P for pattern matching across files — one call returns every match with file paths, line numbers, and previews.

Use this for patterns with special characters or regex operators: ->with\(, ::new\(, fn (get|set)_\w+, \[(derive|test)\], \bAuth\w*Controller\b, alternation a|b, anchors ^$, wildcards .*. Escaping: must escape ( ) [ ] { } . * + ? \\ | ^ $; no escaping needed for -> :: - _ / = < >; in JSON use double backslashes (\\(, \\[).

For simple alphanumeric patterns use search_code instead — it is faster and avoids escaping overhead. For symbol definitions use search_code with symbols: true.

mode: "count" returns {count, pattern} only. List-mode result shape is columnar: {columns, rows} — each row aligns positionally to columns (path, language, start_line, end_line, preview; then kind/symbol/context when present). Set env REFLEX_MCP_COLUMNAR=0 for the legacy results[] shape. Pagination: if response.pagination.has_more is true, fetch the next page with offset. On "Index not found" / "stale" error, call index_project, then retry.

Structure-aware search using Tree-sitter AST patterns (S-expressions). ⚠️ SLOW: bypasses trigram optimization and scans the ENTIRE codebase (500ms-10s+). In 95% of cases, prefer search_code with symbols: true instead (10-100x faster).

Use this only when you must match code structure rather than text: "all async functions containing a match expression", "every class with a serialize method", etc. You MUST pass glob to limit scope — without it, every file in the codebase is parsed.

Example patterns — Rust: (function_item) @fn; Python: (function_definition) @fn; TypeScript: (class_declaration) @class. Refer to Tree-sitter grammar docs for each language. On "Index not found" / "stale" error, call index_project, then retry.

Rebuild or update the code search index. Call this whenever any Reflex search tool returns an "Index not found" or "stale" error — the retry will then succeed. Also call after large git operations (checkout, merge, rebase, pull), user file edits, or when results seem stale or missing.

Incremental by default (only changed files re-indexed). Pass force: true for a full rebuild when the index appears corrupted.

List every import (dependency) of a single file. Prefer this over grep-ing for import / use / require statements — Reflex answers from its pre-built import index, which grep cannot replicate without scanning every file. Returns one object per import with path, line, type (internal/external/stdlib), and optional symbols.

Use this for: understanding file dependencies, analyzing import structure, finding what a file depends on. Path matching is fuzzy — exact paths, fragments, or bare filenames all work. Only static imports (string literals) are extracted; dynamic imports are filtered by design. On "Index not found" / "stale" error, call index_project, then retry.

Reverse dependency lookup — find every file that imports a given file. Prefer this over grep-based find-callers: Reflex answers from its pre-built reverse-import index in one call, which grep cannot replicate without scanning every file. Returns the list of importing file paths.

Use this for: impact analysis before changing a module; finding consumers of a library; detecting file importance. Path matching is fuzzy — exact paths, fragments, or bare filenames all work. Only static imports (string literals) are considered; dynamic imports are filtered by design. On "Index not found" / "stale" error, call index_project, then retry.

Walk the transitive dependency tree of a file up to depth levels (default 3). Prefer this over hand-rolling recursive grep across imports — Reflex traverses the static import graph directly, returning a map of file → depth.

Use this for: understanding the full dependency chain, analyzing deep coupling, planning refactoring blast radius. Example: depth=2 finds file → deps → deps of deps. Only static imports (string literals) are followed; dynamic imports are filtered by design. On "Index not found" / "stale" error, call index_project, then retry.

Rank files by how many other files import them (dependency hotspots). Prefer this over any grep-based "most-imported file" heuristic — Reflex answers from its pre-built dependency index in one call; grep cannot answer this without scanning every file.

Use this for: finding critical-path files; identifying refactoring blast radius; ranking modules by coupling; architecture review. Returns {pagination, results: [{path, import_count}]} sorted by import count (desc by default; use sort to change). Default page size 200; if pagination.has_more is true, fetch the next page with offset. Only static imports are counted. On "Index not found" / "stale" error, call index_project, then retry.

Example: {"results": [{"path": "src/models.rs", "import_count": 27}]}

Detect circular dependencies (cycles A → B → C → A) in the static import graph. Prefer this over manually grepping for import chains — Reflex does the cycle detection directly. Returns {pagination, results: [{paths: ["a.rs", "b.rs", "a.rs"]}]}, sorted with longest cycles first by default. Default page size 200; if pagination.has_more is true, fetch the next page with offset. Only static imports are considered. On "Index not found" / "stale" error, call index_project, then retry.

List files that no other file imports — orphan candidates for deletion. Prefer this over manual Glob + Grep cross-referencing — Reflex answers from the static import graph in one call. Returns {pagination, results: ["src/unused.rs", "tests/old.rs", ...]}. Default page size 200; if pagination.has_more is true, fetch the next page with offset. Note: entry points (main.rs, index.ts) appear as unused by design — do not delete them. Only static imports are considered. On "Index not found" / "stale" error, call index_project, then retry.

Find disconnected components (islands) in the static import graph — groups of files that have no imports crossing group boundaries. Prefer this over manual Glob + Grep cluster analysis — Reflex computes the connected components directly. Returns {pagination, results: [{island_id, size, paths: [...]}]} sorted with largest islands first by default. Default page size 200; if pagination.has_more is true, fetch the next page with offset. Use min_island_size and max_island_size to filter by component size (default: 2–500 files, or 50% of total). Only static imports are considered. On "Index not found" / "stale" error, call index_project, then retry.

One-call overview of codebase dependency health. Prefer this over running find_circular + find_hotspots + find_unused + find_islands individually — returns aggregate counts so the agent can decide which specific analysis to drill into. Returns {circular_dependencies, hotspots, unused_files, islands, min_dependents}. Only static imports are considered. On "Index not found" / "stale" error, call index_project, then retry.

Example: {"circular_dependencies": 17, "hotspots": 10, "unused_files": 82, "islands": 81, "min_dependents": 2}

Atomic symbol definition + every usage in one call. Prefer this over the two-step Grep-based find-all-callers pattern (grep -rn X then filter to call sites by eye) and over chaining search_code(symbols=true) + search_code() — find_references returns both the definition and all call sites in a single call, complete with no follow-up searches needed.

Use this for: "find all callers of X" (the most common agent refactoring task); impact analysis before changing a function or class; rename planning; dead-code detection before deleting a function.

By default, matches inside string literals and comments are excluded (so test fixtures and doc comments don't drown out real call sites); pass include_strings: true to restore all occurrences. Returns {definition, references, total_references, pagination, status} where definition is the first symbol definition ({path, line, kind, symbol, span, preview}) or null, and references is a flat array of {path, line, preview} covering every textual occurrence including the definition site itself. Pagination applies to references only; if pagination.has_more is true, fetch the next page with offset. On "Index not found" / "stale" error, call index_project, then retry.

One-shot codebase orientation: structure, file types, project type, frameworks, entry points, test layout, config files. Prefer this over Glob-based recon at session start — Reflex returns a single consolidated overview instead of multiple glob calls. By default (no parameters) all context types are gathered; pass individual flags (structure, framework, entry_points, etc.) for a focused slice. Use depth to control tree depth (default 2) and path to focus on a subdirectory.

Use this for: getting oriented in an unfamiliar codebase; locating entry points; confirming which frameworks/languages are in use. For finding where a specific symbol/pattern lives, use search_code or find_references instead.

Check whether the Reflex search index is fresh, stale, or missing — without running any search. Call this once at session start and before any bulk search/refactoring task; if status is stale or missing, call index_project before searching.

Returns {status: "fresh" | "stale" | "missing", reason, action_required, files_modified?}. Useful after git operations (checkout, merge, rebase, pull) that may have moved HEAD off the indexed commit; reason explains the staleness and action_required gives the fix command (always rfx index when stale).

Example fresh: {"status": "fresh"}. Example stale: {"status": "stale", "reason": "Commit changed from abc1234 to def5678", "action_required": "rfx index"}