ast-grep

name: ast-grep description: "Searches and rewrites code using AST patterns. Use when finding code patterns, refactoring at scale, or detecting anti-patterns across a codebase."

ast-grep (ast-grep or sg) searches code by AST structure, not text. Patterns must be valid parseable code with $VAR meta-variables for wildcards.

Core Commands

# Search with pattern
ast-grep run -l ts --pattern 'console.log($X)' src/

# Search in directory (auto-detects language)
ast-grep run --pattern '$FUNC()' agent/extensions/

Pattern Syntax

• $VAR — matches single AST node (uppercase only: $MOD, $_, $_123)
• $$$VAR — matches zero or more nodes (function args, statements)
• $_VAR — non-capturing (same name can match different content)
• Patterns must be valid code: import { $X } from "$Y" works, from $X fails

Common Patterns

Find re-exports (barrel files)

ast-grep run -l ts --pattern 'export * from "$Y"' ./
ast-grep run -l ts --pattern 'export { $$$X } from "$Y"' ./
ast-grep run -l ts --pattern 'export type * from "$Y"' ./

Find all imports from a module

ast-grep run -l ts --pattern 'import { $$$X } from "$MOD"' ./

Find function calls with specific structure

ast-grep run -l ts --pattern 'console.log($MSG)' ./
ast-grep run -l ts --pattern 'fetch($URL).then($H)' ./

Detect anti-patterns

# await inside Promise.all
ast-grep run -l ts --pattern 'await $X' ./ \
  --selector call_expression \
  --pattern 'Promise.all($$_)'

Tips

• Use --debug-query=ast to see parsed AST structure
• Check playground for pattern validation
• Patterns fail silently if not parseable — verify with --debug-query