ast-grep

name	ast-grep
description	AST-structured code search and rewrite using ast_grep_search / ast_grep_replace tools. Use when the pattern depends on code structure (function/class/import/call shape) rather than plain text.

ast-grep

When to use these tools vs built-in grep

• Use ast_grep_search when the search depends on code structure: "find all console.log calls", "find all functions named parse", "find imports from a specific module". Plain-text grep misses structure.
• Use the built-in grep/bash rg/ag/grep for plain-text, regex, or cross-language searches where AST awareness is not needed.
• ast_grep_replace rewrites code structurally across many files. Prefer it over per-file edit for bulk structural changes.

Pattern rules

• Patterns must be complete AST nodes — valid code in the target language.
• $VAR matches a single AST node (expression, statement, identifier).
• $$$ matches zero or more AST nodes (e.g., function arguments, statement list).
• Patterns use meta-variables, not regex. $MSG is not (.*).

Tools

ast_grep_search

Param	Type	Description
pattern	string	AST pattern (required)
lang	string	Target language (see below)
paths	string[]	Paths to search (default: cwd)
globs	string[]	Include/exclude globs (prefix ! to exclude)
context	number	Context lines around each match

Returns file:line:column locations with surrounding code.

ast_grep_replace

Same params plus:

Param	Type	Description
rewrite	string	Replacement using $VAR from pattern
dryRun	boolean	Preview only (default: true). Pass false to apply.

executionMode: "sequential" — runs one at a time, never parallel.

Languages

25 supported: bash, c, cpp, csharp, css, elixir, go, haskell, html, java, javascript, json, kotlin, lua, nix, php, python, ruby, rust, scala, solidity, swift, typescript, tsx, yaml.

Prerequisite

sg must be on PATH. Install:

brew install ast-grep
# or: npm install -g @ast-grep/cli
# or: cargo install ast-grep --locked

The extension disables itself (with a console warning) if sg is missing.

Examples

Good patterns (AST-aware)

console.log($MSG)              → finds all console.log calls
function $NAME($$$) { $$$ }    → finds any function
import { $THING } from "..."   → finds named imports
$LEFT = $RIGHT                 → finds any assignment
class $NAME { $$$ }            → finds any class

Bad patterns (plain text, not AST)

console\.log\(.*\)              → use ast_grep_search instead: console.log($MSG)
function\s+\w+\s*\(            → use pattern: function $NAME($$$) { $$$ }
import.*from                    → use pattern: import { $$$ } from $SRC