🔍 AST-Grep structural code search tool

Performs powerful structural code search using ast-grep's pattern matching capabilities. Unlike text-based search, this matches syntactical AST node structures.

Key Features:

• Structural pattern matching (not just text)

• Multi-language support (JS, TS, Python, Go, Rust, etc.)

• Wildcard variables ($VAR, $FUNC, $ARGS)

• Precise code location information

• Fast Rust-based execution with performance optimizations

• Comprehensive pattern validation with helpful error messages

• 120-second timeout for very large projects

• Automatic respect for .gitignore files (no manual exclusions needed)

Pattern Syntax:

• Use $ + UPPERCASE for wildcards: $FUNC, $VAR, $ARGS

• Patterns look like real code: 'function $NAME($ARGS) { $BODY }'

• Match specific constructs: 'new $CLASS($ARGS)'

• Valid characters: (), {}, [], "", '', numbers, operators, keywords

• NOT regex: do NOT use '|', '.*', '.+', '/pattern/', or escapes like '(' or '{'.

Common Mistakes to Avoid: ❌ Don't use: 'function $FUNC' (ambiguous, multiple AST interpretations) ❌ Don't use: 'export $TYPE' (ambiguous, multiple AST interpretations) ❌ Don't use: '$NAME' (too generic, matches everything) ❌ Don't use: /pattern/ (regex syntax not supported)

✅ Good Patterns:

• 'function $NAME($ARGS) { $BODY }' (complete function structure)

• 'export const $NAME = $VALUE' (exported constant)

• 'import $NAME from "$MODULE"' (import statement)

• 'new $CLASS($ARGS)' (constructor call)

• 'def ' (Python function definitions)

• 'class $NAME:' (Python class)

• 'await $PROMISE' inside 'for ($COND) { $BODY }' (relational patterns)

Examples:

• Find all functions: 'function $NAME($ARGS) { $BODY }'

• Find all exports: 'export const $NAME = $VALUE'

• Find imports: 'import $NAME from "$MODULE"'

• Find class instantiation: 'new $CLASS($ARGS)'

• Find method calls: '$OBJ.$METHOD($ARGS)'

• Find async functions: 'async function $NAME($ARGS) { $BODY }'

• Find arrow functions: 'const $NAME = ($ARGS) => $BODY'

• Find React components: 'export function $NAME($PROPS) { return $JSX }'

• Find Python function definitions: 'def '

• Find Python classes: 'class $NAME:'

Advanced Usage:

• Use $$$ for zero or more arguments: 'console.log($$$ARGS)'

• Use relational rules: 'await $PROMISE' inside 'for ($COND) { $BODY }'

• Use multiple searches for OR conditions (alternation not supported)

Direct CLI Usage (for agents with command line access): Agents with command line access can run ast-grep directly:

Basic usage

npx ast-grep --pattern "function $NAME($ARGS) { $BODY }" --lang ts

Python function definitions

npx ast-grep --pattern "def " --lang py

Python classes

npx ast-grep --pattern "class $NAME:" --lang py

With file filtering (recommended for large projects)

npx ast-grep --pattern "def " --lang py src/**/*.py

JSON output

npx ast-grep --pattern "class $NAME:" --lang py --json=stream

Full documentation

npx ast-grep --help

Note: ast-grep respects .gitignore files automatically - no --exclude-dir flags needed

Use Cases:

• Code refactoring and migration

• Finding specific patterns across codebase

• Security auditing for dangerous patterns

• Architecture analysis and dependency tracking

• Finding unused imports or exports

• API usage analysis

Performance Optimizations for Large Projects:

• 120-second timeout for very large projects

• Automatically respects .gitignore files for exclusions

• For additional exclusions, configure .gitignore in your project

Tips for Large Projects (like D:\Dev\SWE-agent):

• Use filePattern to search specific directories: "src/**/*.py"

• Add large directories to .gitignore: node_modules/, tests/, docs/, etc.

• Consider CLI usage for better performance: npx ast-grep --pattern "import json" --lang py src/**/*.py