search_ast
Match code structure using AST patterns to find functions, classes, or custom syntactic structures beyond text search.
Instructions
⚠️ 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dependencies | No | Include dependency information (imports) in results. Only extracts static imports. | |
| exclude | No | Exclude files matching glob patterns (e.g., ['target/**', 'node_modules/**']) | |
| file | No | Filter by file path (substring) | |
| force | No | Force execution of potentially expensive queries (bypasses broad query detection) | |
| glob | No | Include files matching glob patterns (STRONGLY RECOMMENDED to limit scope, e.g., ['src/**/*.rs']) | |
| lang | Yes | Language (REQUIRED: rust, typescript, javascript, python, go, java, c, cpp, csharp, php, ruby, kotlin, zig) | |
| limit | No | Maximum number of results (use with offset for pagination) | |
| offset | No | Pagination offset (skip first N results after sorting) | |
| paths | No | Return only unique file paths | |
| pattern | Yes | AST pattern (Tree-sitter S-expression, e.g., '(function_item) @fn') |