use-ast-grep

AST-Grep Integration Protocol for Cursor Agent

When to Use AST-Grep

Use ast-grep (if installed) instead of plain regex or text search when:

• Structural code patterns are involved (e.g., finding all function calls, class definitions, or method implementations)
• Language-aware refactoring is required (e.g., renaming variables, updating function signatures, or changing imports)
• Complex code analysis is needed (e.g., finding all usages of a pattern across different syntactic contexts)
• Cross-language searches are necessary (e.g., working with both Ruby and TypeScript in a monorepo)
• Semantic code understanding is important (e.g., finding patterns based on code structure, not just text)

AST-Grep Command Patterns

Basic Search Template:

ast-grep --pattern '$PATTERN' --lang $LANGUAGE $PATH

Common Use Cases

• Find function calls: ast-grep --pattern 'functionName($$$)' --lang javascript .
• Find class definitions: ast-grep --pattern 'class $NAME { $$$ }' --lang typescript .
• Find variable assignments: ast-grep --pattern '$VAR = $$$' --lang ruby .
• Find import statements: ast-grep --pattern 'import { $$$ } from "$MODULE"' --lang javascript .
• Find method calls on objects: ast-grep --pattern '$OBJ.$METHOD($$$)' --lang typescript .
• Find React hooks: ast-grep --pattern 'const [$STATE, $SETTER] = useState($$$)' --lang typescript .
• Find Ruby class definitions: ast-grep --pattern 'class $NAME < $$$; $$$; end' --lang ruby .

Pattern Syntax Reference

• $VAR — matches any single node and captures it
• $$$ — matches zero or more nodes (wildcard)
• $$ — matches one or more nodes
• Literal code — matches exactly as written

Supported Languages

• javascript, typescript, ruby, python, go, rust, java, c, cpp, html, css, yaml, json, and more

Integration Workflow

Before using ast-grep:

1. Check if ast-grep is installed: If not, skip and fall back to regex/semantic search.

   command -v ast-grep >/dev/null 2>&1 || echo "ast-grep not installed, skipping AST search"
   

2. Identify if the task involves structural code patterns or language-aware refactoring.
3. Determine the appropriate language(s) to search.
4. Construct the pattern using ast-grep syntax.
5. Run ast-grep to gather precise structural information.
6. Use results to inform code edits, refactoring, or further analysis.