ast-grep

name	ast-grep
description	AST-based code search and rewrite via tree-sitter patterns. Use instead of Grep/Edit when a change spans many sites or must respect code structure: structural matching, multi-file batch rewrites, or context-aware queries (e.g. "unwrap inside impl blocks"). Not for a single-file or single-symbol rename — use Edit for that.
allowed-tools	Bash(mise exec -- ast-grep *), Read, Glob

ast-grep

Matches code by parsed AST, not text. Supports metavariable capture, relational rules, and in-place rewrite.

All commands must be run through mise exec -- since ast-grep is installed via mise:

Commands

# Pattern search
mise exec -- ast-grep run -p '$X.unwrap()' -l rust .

# Rewrite: always preview first, then apply with -U
mise exec -- ast-grep run -p '$X.lock().unwrap()' -l rust .
mise exec -- ast-grep run -p '$X.lock().unwrap()' -r '$X.lock().expect("lock poisoned")' -l rust -U .

# Structural search with YAML rules (for relational/composite logic)
mise exec -- ast-grep scan --inline-rules 'id: name
language: rust
rule:
  pattern: $X.unwrap()
  inside:
    kind: impl_item
    stopBy: end' .

# JSON output for programmatic use
mise exec -- ast-grep run -p '$X.unwrap()' -l rust --json .

# Debug: see how ast-grep parses your pattern or target code
mise exec -- ast-grep run -p 'PATTERN' -l rust --debug-query=cst   # concrete syntax tree
mise exec -- ast-grep run -p 'PATTERN' -l rust --debug-query=pattern # metavar detection