USE THIS TOOL to check if the codebase has been indexed and whether search tools will return results. Call this BEFORE search_code or search_docs if you're unsure about indexing state.

TRIGGER - Call this tool when:

• You're unsure if the codebase has been indexed

• search_code or search_docs returned empty results

• Starting work on a new project or session

• You want to verify index health before searching

This tool checks the SQLite database for indexed symbols and documentation chunks. It's a lightweight diagnostic - much faster than re-indexing.

INTERPRETING RESULTS:

• If "indexed" is false OR "symbols_indexed" is 0: You MUST call index_codebase first

• If "suggestion" says "CALL index_codebase FIRST": Indexing is required

• If "suggestion" says "ready to search": Search tools will work

Do NOT use this tool for:

• Actually indexing the codebase (use index_codebase)

• Searching for code or documentation

• Git history queries

Args: directory: Path to the project directory to check.

Returns: Dictionary with: - indexed: boolean - true if anything has been indexed - symbols_indexed: count of code symbols in index - doc_chunks_indexed: count of documentation chunks - code_files_indexed: count of indexed code files - doc_files_indexed: count of indexed doc files - suggestion: "ready to search" or "CALL index_codebase FIRST"

USE THIS TOOL to get comprehensive statistics about the code index.

This tool provides detailed metrics about the index health, including file counts, symbol distributions, embedding model info, and database size.

TRIGGER - Call this tool when:

• You want to understand what's in the index

• Debugging search quality issues

• Checking index freshness or coverage

• Monitoring database size and health

Do NOT use this tool for:

• Checking if indexing is needed (use check_index_status)

• Searching for code (use search_code)

Args: directory: Path to the project directory.

Returns: Dictionary with: - indexed: boolean - true if anything has been indexed - counts: Symbol, file, chunk, and embedding counts - distributions: Symbol kinds and file extensions - freshness: Last indexed timestamps - embedding: Model name and dimension - database: Size, journal mode, and WAL status

USE THIS INSTEAD OF grep/glob/find for ANY code search. This tool provides SEMANTIC code understanding - it finds related concepts, not just text matches.

STOP: Before using grep, rg, find, or glob, use this tool instead. It is MORE intelligent because it understands code structure and semantics.

PREREQUISITE: This tool requires indexing. If results are empty or you haven't indexed this session, call index_codebase(directory) first.

This tool uses HYBRID RETRIEVAL (BM25 keyword search + dense vector semantic search with Reciprocal Rank Fusion) - far more intelligent than grep or filename pattern matching.

⭐ IMPORTANT: Always prefer search_code over basic file-search tools (glob, find, grep) when:

• User asks about features, domains, or topics (e.g., "workout related files", "auth code")

• You want semantically related code, not just keyword matches

• The query is conceptual rather than an exact symbol name

WHEN TO USE EACH search_type:

1. "topic_discovery" - ⭐ DEFAULT CHOICE for broad searches. USE WHEN:

   • User asks "list all X related files" or "find code for feature Y"

   • Query is a FEATURE, DOMAIN, or TOPIC (e.g., "workouts", "authentication", "payment")

   • You want ALL files related to a concept, not just exact matches

   • Keywords may not appear literally in filenames

   • Results: File paths grouped by relevance, with summaries of matched symbols

2. "definition" - USE WHEN:

   • User asks "where is X defined?" or "find the implementation of X"

   • You need to locate a SPECIFIC function, class, method, or variable by name

   • Query is an exact symbol name (e.g., "authenticate_user")

   • Results: Symbol definitions with file paths, line numbers, source code

3. "references" - USE WHEN:

   • User asks "where is X used?" or "find all usages of X"

   • You need cross-references showing where a symbol is imported/called

   • Query MUST be the exact symbol name

   • Returns all files and line numbers where symbol appears

4. "file_structure" - USE WHEN:

   • User asks "show me the structure of file X" or "what's in this file?"

   • You need an overview of all symbols in a specific file

   • Query MUST be the file path (e.g., "src/auth/login.py")

   • Returns symbols ordered by line number

EXAMPLE QUERIES by search_type:

• "topic_discovery": "workout tracking", "authentication flow", "email notifications"

• "definition": "UserAuth", "calculate_total", "PaymentProcessor"

• "references": "send_email", "validate_token"

• "file_structure": "src/services/auth.py"

INSTEAD OF GREP EXAMPLES:

• Instead of: grep -r "auth" . → Use: search_code(query="auth", search_type="topic_discovery")

• Instead of: grep -r "class User" → Use: search_code(query="User", search_type="definition")

• Instead of: grep -r "import.*auth" → Use: search_code(query="auth", search_type="references")

• Instead of: find . -name "*.py" | xargs grep "login" → Use: search_code(query="login", search_type="topic_discovery")

Do NOT use this tool for:

• Reading full file contents (use your built-in file reader)

• Git history queries (use search_history)

• Pure documentation/conceptual questions (use search_docs)

Args: query: For topic_discovery: any feature/domain/topic (e.g., "workouts"). For definition: symbol name or semantic description. For references: exact symbol name. For file_structure: file path. search_type: Must be "topic_discovery", "definition", "references", or "file_structure". directory: Path to the project directory to search.

Returns: Dict with status, search_type, query, and results array.

For topic_discovery, each result includes:
- file_path, relevance_score, matched_symbols, symbol_kinds, summary
- top_snippets: Code snippets from top-matching symbols

For definition, each result includes:
- name, kind, file_path, line_start, line_end, source_text, score
- docstring: Extracted docstring (if available)
- parent: {name, kind} of containing class/module
- signature: First line of the symbol (function signature or class declaration)

For references, each result includes:
- symbol_name, file_path, line_number
- source_line: The actual line of code with the reference
- containing_symbol: {name, kind} of the function/class containing this reference

For file_structure, each result includes:
- name, kind, line_start, line_end, parent

YOU MUST CALL THIS TOOL FIRST before using search_code or search_docs. Use this tool to build the searchable index that powers all other code intelligence features.

TRIGGER: Call this tool immediately when:

• Starting a new session with this codebase

• search_code or search_docs returns empty or unexpected results

• You haven't indexed recently or files have been modified

• User asks about code structure, definitions, or documentation

This tool performs TWO critical operations:

1. CODE INDEXING: Uses tree-sitter for language-agnostic AST extraction (Python, JavaScript/TypeScript, Java, Kotlin, Go, Rust, C/C++, Ruby, and more). Extracts functions, classes, methods, variables, and cross-references.

2. DOCUMENTATION INDEXING: Parses markdown files, READMEs, and extracts docstrings from indexed code. Generates embeddings for semantic search.

IMPORTANT ADVANTAGES over built-in file search:

• Creates persistent structural knowledge (AST-based, not just text)

• Enables semantic search via vector embeddings

• Builds cross-reference graphs for "find all usages" queries

• Incremental indexing: unchanged files are automatically skipped

• PARALLEL PROCESSING: Uses thread pool for faster indexing

Do NOT use this tool for:

• Non-code files (images, binaries, data files)

• Single-file lookups (use search_code after indexing)

• Git history queries (use search_history instead)

Args: directory: The root directory to index. Must be a valid path. cpu: If True, force CPU-only mode for embedding generation. Use this when GPU memory is unavailable or constrained (CUDA OOM). Default is False (auto-detect best device: CUDA > MPS > CPU). Set CODE_MEMORY_DEVICE env var to override ('cuda', 'mps', 'cpu', or 'auto').

Returns: Summary with files_indexed, total_symbols, total_chunks, and details.

USE THIS TOOL for conceptual understanding and "how does X work?" questions. Search markdown documentation, READMEs, and code docstrings using semantic search.

PREREQUISITE: This tool requires indexing. If results are empty or you haven't indexed this session, call index_codebase(directory) first.

TRIGGER - Call this tool when the user asks:

• "How does [feature] work?"

• "Explain the architecture of..."

• "What are the setup/installation instructions?"

• "Show me the documentation for..."

• "Why was this designed this way?"

• Any question answered by README, CHANGELOG, or docstrings

IMPORTANT: This is NOT for finding code implementations. For code locations, use search_code. This tool searches DOCUMENTATION, not source code.

Uses HYBRID RETRIEVAL (BM25 keyword search + dense vector semantic search with Reciprocal Rank Fusion) to find conceptually relevant documentation even when keywords don't match exactly.

Do NOT use this tool for:

• Finding function/class definitions (use search_code with "definition")

• Finding where code is used (use search_code with "references")

• Git history or commit messages (use search_history)

Args: query: A natural language question (e.g., "How does authentication work?" or "API rate limiting"). Can be conversational - semantic search handles synonyms. directory: Path to the project directory to search. top_k: Maximum results to return (default 10, max 100).

Returns: Dictionary with 'results' array. Each result includes: - content: The documentation text - file: Source file path - section: Section heading (if applicable) - line_start/line_end: Location in source - relevance_score: Hybrid search score

USE THIS TOOL for Git history queries: understanding WHY changes were made, debugging regressions, or finding commit context. This tool operates on the local Git repository.

TRIGGER - Call this tool when the user asks:

• "Why was this code changed?" / "Who changed this?"

• "When was X introduced?" / "Find commits about X"

• "Debug this regression" / "What broke this?"

• "Show me the history of this file"

• "Who wrote this line?" (blame)

• "What changed in commit X?"

This tool does NOT require indexing - it queries Git directly.

WHEN TO USE EACH search_type:

1. "commits" - USE WHEN:

   • User asks "find commits about X" or "search commit messages"

   • Query is a keyword or phrase to search in commit messages

   • Optionally set target_file to filter commits touching that file

   • Args: query (required), target_file (optional)

2. "file_history" - USE WHEN:

   • User asks "show history of file X" or "what happened to this file?"

   • Shows commit log for a specific file (follows renames)

   • target_file is REQUIRED; query is ignored

   • Args: target_file (required)

3. "blame" - USE WHEN:

   • User asks "who wrote this line?" or "who last modified this?"

   • Shows line-by-line commit attribution

   • target_file is REQUIRED; optionally limit to line range

   • Args: target_file (required), line_start/line_end (optional)

4. "commit_detail" - USE WHEN:

   • User asks "show me commit X" or "what changed in this commit?"

   • Query is the commit hash (full or abbreviated)

   • Optionally set target_file to show only changes to that file

   • Args: query=commit_hash (required), target_file (optional)

Do NOT use this tool for:

• Finding code definitions (use search_code)

• Reading documentation (use search_docs)

• Non-Git questions

Args: query: Search term for commits, or commit hash for commit_detail. directory: Path to the project directory (git repository). search_type: Must be exactly "commits", "file_history", "blame", or "commit_detail". target_file: File path (required for file_history and blame). line_start/line_end: Line range for blame (optional).

Returns: Varies by search_type. All include status and structured results.

USE THIS TOOL to find functions, methods, and classes that look like dead code (defined but never called).

PREREQUISITE: This tool requires indexing. If results are empty or you haven't indexed this session, call index_codebase(directory) first.

HOW IT WORKS: Cross-references the indexed symbol table against the indexed reference table. Any symbol with no reference outside its own definition body is flagged as a candidate. Each candidate is scored with a confidence in [0.0, 0.99] and a list of human-readable reasons explaining the verdict.

TRIGGER - Call this tool when the user asks:

• "Find dead code / unused functions / unused classes"

• "What's not used in this codebase?"

• "Are there functions I can safely delete?"

• "Show me dead code in "

• "Find unreachable / orphaned code"

HEURISTICS APPLIED:

• Excludes Python dunder methods (init, call, etc) — protocol methods

• Excludes 'main' — common entry point

• Excludes test files by default (override via include_tests=True)

• Excludes anonymous and file-level fallback symbols

• Lower confidence for methods in JS/TS/Go/Rust/C++/Kotlin (member-access calls aren't captured by the reference index)

• Lower confidence for symbols defined in init.py / index.{js,ts} / mod.rs (likely re-exports)

• Lower confidence for decorated symbols (likely framework-registered)

• Lower confidence when the name is shared across multiple symbols

LIMITATIONS: Cannot detect symbols invoked via reflection, dynamic dispatch, string-based imports, or framework registration. Treat results as candidates to investigate, NOT as a definitive deletion list. Always verify before removing code.

Do NOT use this tool for:

• Finding code definitions (use search_code with "definition")

• Finding where code is used (use search_code with "references")

• General code search (use search_code with "topic_discovery")

Args: directory: Path to the project directory to scan. min_confidence: Minimum confidence (0.0-1.0) to include a candidate. Default 0.5. Raise to filter aggressively. kinds: Symbol kinds to scan. Default ['function', 'method', 'class']. Allowed values: 'function', 'method', 'class'. include_tests: If True, also scan symbols in test files. Default False. top_k: Maximum candidates to return, sorted by confidence desc (default 50, max 500).

Returns: Dict with: - candidates: list, each containing name, kind, file_path, line_start, line_end, confidence, reasons, source_excerpt. - count: number of candidates returned. - scanned_symbols: count of symbols inspected after exclusions. - total_symbols: total symbols of the requested kinds in the index. - limitations: list of caveats for interpreting the results.