---

name: ast-search description: Use automatically when searching for code patterns, function usages, API usage, or syntax structures. Trigger on queries like "how is X used", "find usage of", "where is X called", "all calls to X", or "how is X imported". Prefer ast-grep over grep/ripgrep for code-aware searching. allowed-tools:

• Bash
• Read
• Glob
• Grep
• TodoWrite model: sonnet

---

AST-Aware Code Search

Overview

Use ast-grep for syntax-aware code searching that understands language structure. Unlike text-based tools (grep, ripgrep, find), ast-grep matches actual code patterns by parsing the abstract syntax tree.

When to Use

Prefer ast-grep over grep/find when:

• Finding function/method calls: ast-grep -p 'fetchData($$$)'
• Locating class or function definitions
• Searching for specific syntax patterns (hooks, decorators, imports)
• Understanding how an API or function is used across a codebase
• Finding all implementations of a pattern

Use grep/ripgrep instead when:

• Searching for literal strings or comments
• Searching non-code files (markdown, config, logs)
• Simple keyword searches where syntax doesn't matter
• Languages not supported by ast-grep

Quick Reference

# Check installation
which ast-grep || echo "Install with: brew install ast-grep"

# Basic pattern search
ast-grep --pattern 'PATTERN' --lang LANGUAGE [PATH]

# Search with context
ast-grep -p 'PATTERN' -l LANG -A 3 -B 2

# JSON output for parsing
ast-grep -p 'PATTERN' -l LANG --json

Pattern Syntax

Pattern	Matches	Example
$VAR	Single AST node	console.log($MSG) matches console.log("hello")
$$$ARGS	Multiple nodes (named)	function($$$PARAMS) matches any function params
$$$	Any sequence of nodes	{ $$$ } matches any block contents

Supported Languages

javascript, typescript, tsx, python, go, rust, java, c, cpp, csharp, kotlin, swift, ruby, php, lua, html, css

Common Search Patterns

JavaScript/TypeScript

# Find all useState hooks
ast-grep -p 'useState($$$)' -l typescript

# Find specific function calls
ast-grep -p 'fetchUser($$$)' -l typescript

# Find async functions
ast-grep -p 'async function $NAME($$$) { $$$ }' -l typescript

# Find arrow function assignments
ast-grep -p 'const $NAME = ($$$) => $$$' -l typescript

# Find React component definitions
ast-grep -p 'function $COMPONENT($$$): JSX.Element { $$$ }' -l tsx

# Find useEffect with dependencies
ast-grep -p 'useEffect($$$)' -l typescript

# Find imports from a module
ast-grep -p "import { $$$ } from '$MODULE'" -l typescript

# Find class methods
ast-grep -p 'class $CLASS { $$$ $METHOD($$$) { $$$ } $$$ }' -l typescript

Python

# Find function definitions
ast-grep -p 'def $FUNC($$$): $$$' -l python

# Find class definitions
ast-grep -p 'class $CLASS: $$$' -l python

# Find decorator usage
ast-grep -p '@$DECORATOR
def $FUNC($$$): $$$' -l python

# Find specific method calls
ast-grep -p '$OBJ.$METHOD($$$)' -l python

# Find async function definitions
ast-grep -p 'async def $FUNC($$$): $$$' -l python

# Find list comprehensions
ast-grep -p '[$EXPR for $VAR in $ITER]' -l python

Go

# Find function definitions
ast-grep -p 'func $NAME($$$) $$$ { $$$ }' -l go

# Find method definitions
ast-grep -p 'func ($RECV $TYPE) $NAME($$$) $$$ { $$$ }' -l go

# Find interface definitions
ast-grep -p 'type $NAME interface { $$$ }' -l go

# Find struct definitions
ast-grep -p 'type $NAME struct { $$$ }' -l go

# Find error handling patterns
ast-grep -p 'if err != nil { $$$ }' -l go

# Find goroutine spawns
ast-grep -p 'go $FUNC($$$)' -l go

Java

# Find class definitions
ast-grep -p 'class $NAME { $$$ }' -l java

# Find method definitions
ast-grep -p '$RET $METHOD($$$) { $$$ }' -l java

# Find annotations
ast-grep -p '@$ANNOTATION
$$$' -l java

# Find try-catch blocks
ast-grep -p 'try { $$$ } catch ($E) { $$$ }' -l java

Workflow

1. Verify Installation

which ast-grep || brew install ast-grep

2. Identify Target Language

Determine the language flag needed:

• .ts, .tsx → -l typescript or -l tsx
• .js, .jsx → -l javascript
• .py → -l python
• .go → -l go
• .rs → -l rust
• .java → -l java

3. Build Search Pattern

Start simple and refine:

# Start broad
ast-grep -p 'fetchData($$$)' -l typescript

# Add specificity if too many results
ast-grep -p 'await fetchData($$$)' -l typescript

# Narrow to specific directory
ast-grep -p 'fetchData($$$)' -l typescript src/api/

4. Analyze Results

# Count matches
ast-grep -p 'PATTERN' -l LANG --json | jq length

# Get file list only
ast-grep -p 'PATTERN' -l LANG --json | jq -r '.[].file' | sort -u

# Get matches with context
ast-grep -p 'PATTERN' -l LANG -A 5 -B 2

Comparison: ast-grep vs grep

Task	ast-grep	grep/ripgrep
Find log("...") calls	ast-grep -p 'log($$$)' - matches only function calls	rg 'log\(' - matches comments, strings too
Find variable assignments	ast-grep -p 'const $X = $Y' - matches declarations	rg 'const' - matches any occurrence
Find function definitions	ast-grep -p 'function $F($$$)' - accurate	rg 'function' - includes comments, strings
Find class methods	Pattern matches syntax tree	Regex struggles with nesting
Search comments	Not designed for this	Better choice
Search config files	Won't parse non-code	Better choice

Troubleshooting

Pattern doesn't match expected code:

• Verify language flag matches file extension
• Check for whitespace sensitivity in patterns
• Try a simpler pattern first and add specificity
• Use --json output to debug what's matching

Too many results:

• Add more context to the pattern
• Narrow search to specific directories
• Use $NAME instead of $$$ to match single nodes

No results when expecting matches:

• Verify ast-grep supports the language
• Check that files have correct extensions
• Test with a known-good pattern first
• Ensure the pattern syntax matches the language's AST

Performance on large codebases:

• Specify target directories instead of searching entire repo
• Use .astgrepignore file to exclude directories (like node_modules)

Installation

# macOS
brew install ast-grep

# Cargo (Rust)
cargo install ast-grep --locked

# npm (less performant)
npm install -g @ast-grep/cli