Fast location discovery with minimal token usage.

Purpose: Find where a pattern occurs (file + line) without loading previews or detailed context.

Returns: Array of {path, line} objects - one per match location.

Use this when:

• Starting exploration ("where is X used?")

• Counting affected locations

• Building a list for targeted Read operations

• You need locations only, not code content

Workflow:

1. Use list_locations to discover (cheap, returns locations only)

2. Use Read tool or search_code on specific files if you need content (targeted)

Supports: lang, file, glob, exclude filters No limit: Returns ALL matching locations

Error Handling: If you receive an error message containing "Index not found" or "stale", immediately call the index_project tool, wait for it to complete, then retry this operation.

Example: Pattern "CourtCase" → [{"path": "app/Models/CourtCase.php", "line": 15}, {"path": "app/Http/Controllers/CourtController.php", "line": 42}]

Quick statistics - count how many times a pattern occurs.

Purpose: Get total occurrence count and file count without loading any content.

Use this when:

• You need quick stats ("how many times is X used?")

• Checking impact before refactoring

• Validating search scope

Returns: {total: count, files: count, pattern: string}

Supports: All filters (lang, file, glob, exclude, symbols)

Error Handling: If you receive an error message containing "Index not found" or "stale", immediately call the index_project tool, wait for it to complete, then retry this operation.

Example output: {"total": 87, "files": 12, "pattern": "CourtCase"}

Full-text or symbol-only code search with detailed results.

When to use search_regex instead:

• Patterns with special characters: -> :: () [] {} . * + ? \ | ^ $

• Complex pattern matching: wildcards, alternation, anchors

• Examples: '->with(', '::new', 'function*', '[derive]', 'fn (get|set)_.*'

Search modes:

• Full-text (default): Finds ALL occurrences - definitions + usages

• Symbol-only (symbols=true): Finds ONLY definitions where symbols are declared

Use this for:

• Simple text patterns (alphanumeric, underscores, hyphens)

• Detailed analysis with line numbers and code previews

• Symbol definition searches

Pagination: Check response.pagination.has_more. If true, use offset parameter to fetch next page.

Error Handling: If you receive an error message containing "Index not found" or "stale", immediately call the index_project tool, wait for it to complete, then retry this operation.

Regex-based code search for complex pattern matching (e.g., 'fn (get|set)_\w+').

Use for:

• Patterns with special characters: -> :: () [] {} . * + ? \ | ^ $

• Pattern matching: wildcards (.*), alternation (a|b), anchors (^$)

• Complex searches: case-insensitive variants, word boundaries

Common examples:

• Method calls: '->with\(', '->map\(', '::new\('

• Operators: '->', '::', '||', '&&'

• Functions: 'fn (get|set)_\\w+' (getter/setter functions)

• Attributes: '\\[(derive|test)\\]' (Rust attributes)

Escaping rules:

• Must escape: ( ) [ ] { } . * + ? \ | ^ $

• No escaping needed: -> :: - _ / = < >

• Use double backslash in JSON: \\( \\) \\[ \\]

Error Handling: If you receive an error message containing "Index not found" or "stale", immediately call the index_project tool, wait for it to complete, then retry this operation.

Don't use for:

• Simple text searches (use search_code instead - faster)

• Symbol definitions (use search_code with symbols=true instead)

⚠️ ADVANCED USERS ONLY - DO NOT USE UNLESS ABSOLUTELY NECESSARY ⚠️

Structure-aware code search using Tree-sitter AST patterns (S-expressions).

PERFORMANCE WARNING: AST queries bypass trigram optimization and scan the ENTIRE codebase (500ms-10s+).

WHEN TO USE (RARE):

• You need to match code structure, not just text (e.g., "all async functions with try/catch blocks")

• --symbols search is insufficient (e.g., need to match specific AST node types)

• You have a very specific structural pattern that cannot be expressed as text

IN 95% OF CASES, USE search_code with symbols=true INSTEAD (10-100x faster).

REQUIRED: You MUST use glob patterns to limit scope (e.g., glob=['src/**/*.rs']) to avoid scanning thousands of files.

Token efficiency: Previews are auto-truncated to ~100 chars. Use limit parameter to control result count.

Error Handling: If you receive an error message containing "Index not found" or "stale", immediately call the index_project tool, wait for it to complete, then retry this operation.

Example AST patterns:

• Rust: '(function_item) @fn' (all functions)

• Python: '(function_definition) @fn' (all functions)

• TypeScript: '(class_declaration) @class' (all classes)

Refer to Tree-sitter documentation for each language's grammar.

Rebuild or update the code search index. Run this when:

• After code changes (user edits, git operations, file creation/deletion)

• Search results seem stale or missing new files

• Empty/error results (may indicate missing/corrupt index)

Modes:

• Incremental (default): Only re-indexes changed files (fast)

• Full rebuild (force=true): Re-indexes everything (use if index seems corrupted)

Get all dependencies (imports) of a specific file.

Purpose: Analyze what modules/files a given file imports.

Returns: Array of dependency objects with import path, line number, type (internal/external/stdlib), and optional symbols.

Use this when:

• Understanding file dependencies

• Analyzing import structure

• Finding what a file depends on

IMPORTANT: Only extracts static imports (string literals). Dynamic imports (variables, template literals, expressions) are automatically filtered by tree-sitter query design. See CLAUDE.md section "Dependency/Import Extraction" for details.

Note: Path matching is fuzzy - supports exact paths, fragments, or just filenames.

Get all files that depend on (import) a specific file.

Purpose: Find what other files import this file (reverse dependency lookup).

Returns: Array of file paths that import the specified file.

Use this when:

• Understanding impact of changes

• Finding usages of a module

• Analyzing file importance

IMPORTANT: Only considers static imports (string literals). Dynamic imports are filtered. See CLAUDE.md section "Dependency/Import Extraction" for details.

Note: Path matching is fuzzy - supports exact paths, fragments, or just filenames.

Get transitive dependencies of a file up to a specified depth.

Purpose: Find not just direct dependencies, but dependencies of dependencies (the full dependency tree).

Returns: Object mapping file IDs to their depth in the dependency tree.

Use this when:

• Understanding full dependency chain

• Analyzing deep coupling

• Planning refactoring impact

IMPORTANT: Only follows static imports (string literals). Dynamic imports are filtered. See CLAUDE.md section "Dependency/Import Extraction" for details.

Example: depth=2 finds: file → deps → deps of deps

Find the most-imported files in the codebase (dependency hotspots).

Purpose: Identify files that many other files depend on.

Pagination: Default limit of 200 results per page. Check response.pagination.has_more to fetch more pages.

Sorting: Default order is descending (most imports first). Use sort parameter to change.

Returns: Object with pagination metadata and array of {path, import_count} objects sorted by import count.

Use this when:

• Finding critical files

• Identifying potential bottlenecks

• Understanding architecture

• Planning refactoring priorities

IMPORTANT: Only counts static imports (string literals). Dynamic imports are filtered. See CLAUDE.md section "Dependency/Import Extraction" for details.

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

Detect circular dependencies in the codebase.

Purpose: Find dependency cycles (A → B → C → A).

Pagination: Default limit of 200 results per page. Check response.pagination.has_more to fetch more pages.

Sorting: Default order is descending (longest cycles first). Use sort parameter to change.

Returns: Object with pagination metadata and array of cycles, where each cycle is an array of file paths forming the circular path.

Use this when:

• Debugging circular dependency issues

• Improving code architecture

• Validating refactoring

IMPORTANT: Only detects cycles in static imports (string literals). Dynamic imports are filtered. See CLAUDE.md section "Dependency/Import Extraction" for details.

Note: Circular dependencies can cause compilation issues and indicate architectural problems.

Example output: {"pagination": {...}, "results": [{"paths": ["a.rs", "b.rs", "a.rs"]}]}

Find unused files that no other files import.

Purpose: Identify orphaned files that could be safely removed.

Pagination: Default limit of 200 results per page. Check response.pagination.has_more to fetch more pages.

Returns: Object with pagination metadata and flat array of file path strings (no wrapping objects).

Use this when:

• Cleaning up dead code

• Reducing codebase size

• Identifying test-only or entry-point files

Note: Entry points (main.rs, index.ts) will appear as unused but should not be deleted.

Example output: {"pagination": {...}, "results": ["src/unused.rs", "tests/old.rs"]}

Find disconnected components (islands) in the dependency graph.

Purpose: Identify groups of files that are isolated from the rest of the codebase (no dependencies between groups).

Pagination: Default limit of 200 results per page. Check response.pagination.has_more to fetch more pages.

Sorting: Default order is descending (largest islands first). Use sort parameter to change.

Returns: Object with pagination metadata and array of islands, where each island contains multiple file paths that depend on each other.

Use this when:

• Identifying isolated subsystems

• Understanding codebase modularity

• Finding potential code splitting opportunities

• Detecting disconnected feature modules

IMPORTANT: Only considers static imports (string literals). Dynamic imports are filtered. See CLAUDE.md section "Dependency/Import Extraction" for details.

Size filtering: Use min_island_size and max_island_size to filter by component size. Default: 2-500 files (or 50% of total files).

Example output: {"pagination": {...}, "results": [{"island_id": 1, "size": 5, "paths": ["a.rs", "b.rs", "c.rs", "d.rs", "e.rs"]}]}

Get a summary of all dependency analyses.

Purpose: Quick overview of codebase dependency health.

Returns: Object with counts: {circular_dependencies, hotspots, unused_files, islands, min_dependents}

Use this when:

• Getting a quick health check of the codebase

• Understanding overall dependency structure

• Deciding which specific analysis to run next

IMPORTANT: Only considers static imports (string literals). Dynamic imports are filtered. See CLAUDE.md section "Dependency/Import Extraction" for details.

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

Find a symbol's definition AND all usage sites in a single call.

Purpose: Eliminates the two-step pattern of search_code(symbols=true) + search_code(). Returns both the definition and all usages atomically.

Returns: {definition, references, total_references, pagination, status}

Use this when:

• "Find all callers of X" — the most common agent refactoring pattern

• Code review: understand impact before changing a function or class

• Rename planning: see every site that needs updating

• Dead code detection: confirm nothing calls a function before removing it

definition: First matching symbol definition {path, line, kind, symbol, span, preview}, or null if no symbol definition exists for the pattern.

references: Flat array of {path, line, preview} — all textual occurrences including the definition site itself.

Pagination applies to references only. Use limit and offset. Check pagination.has_more for more pages.

Error Handling: If you receive an error message containing "Index not found" or "stale", immediately call the index_project tool, wait for it to complete, then retry this operation.

Collects comprehensive codebase information.

Parameters:

• structure (bool): Show directory tree

• file_types (bool): Show file type distribution

• project_type (bool): Detect project type (CLI/library/webapp)

• framework (bool): Detect frameworks (React, Django, etc.)

• entry_points (bool): Find main/index files

• test_layout (bool): Show test organization

• config_files (bool): List configuration files

• depth (int): Tree depth for structure (default: 2)

• path (string, optional): Focus on specific directory

When to use:

• Understanding project structure and organization

• Finding which frameworks/languages are used

• Locating entry points and test layouts

• Getting file statistics and distribution

When NOT to use:

• Finding conceptual/architectural information (use search_documentation)

• Understanding high-level how things work (use search_documentation)

Note: By default (no parameters), all context types are gathered.

Check whether the Reflex search index is fresh, stale, or missing — without running any search.

CALL THIS FIRST at the start of every session and before any significant search task. If the index is stale or missing, call index_project before searching.

Returns:

• status: "fresh" | "stale" | "missing"

• reason: why the index is stale (branch not indexed, commit changed, files modified)

• action_required: command to fix the issue (always rfx index when stale)

• files_modified: number of recently modified files detected (only present for mtime-based staleness)

When to call:

• At the start of every agent session

• Before any bulk search or refactoring task

• After a git operation (checkout, merge, rebase, pull)

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