Ast Grep

ast-grep

sg (also installed as ast-grep) is an AST-aware search and rewrite tool across 25 languages. It treats your pattern as code, parses it the same way it parses your project, and matches structurally. It is the right tool whenever your question depends on code shape rather than text bytes.

This skill ships a Python wrapper at scripts/ast_grep_helper.py and platform install scripts at install.sh (POSIX) and install.ps1 (Windows). The helper adds offline pattern validation, the two-pass write trick, and binary auto-resolution. Use it as your default entry point.

---

When to use this skill

Use it whenever the user's question is about code structure, not bytes:

• "Find every function that takes a Request parameter."
• "Rewrite every console.log(x) to logger.info(x)."
• "Strip every as any cast."
• "Replace require(...) with import across the repo."
• "Find empty catch blocks."
• "Migrate Optional[X] to X | None."
• "Apply this codemod across these 200 files."
• "Run our YAML lint rules and surface violations."

Switch to plain grep / rg when the question is text-shaped (string literal contents, comments, license headers, file names, cross-language regex). When in doubt, ask: "does the answer depend on the language's syntax tree, or just on the file's bytes?" If the former, ast-grep. If the latter, grep.

---

Three things the agent must internalize

1. ast-grep is NOT regex

The wildcards are $VAR (one AST node) and $$$ (zero or more nodes). Regex syntax fails silently:

The full anti-pattern table is in references/pitfalls.md §1. The helper's validate subcommand catches these mechanically — call it before debugging "no matches" by hand.

2. Patterns must be valid code

The pattern itself must parse. def $FN($$$): fails because the trailing : makes it incomplete; use def $FN($$$). function $NAME without params/body fails; use function $NAME($$$) { $$$ }. Full table per language in references/pitfalls.md §2.

3. --update-all and --json are mutually exclusive (silently)

This is the single biggest gotcha when scripting. sg run -p P -r R --json --update-all returns the JSON but does not mutate files. To both preview AND apply, run two passes:

sg run -p P -r R --json=compact .   # pass 1: see what would change
sg run -p P -r R --update-all .     # pass 2: actually apply

The helper does this automatically when you call replace --apply. Read references/pitfalls.md §9.

---

The helper script — scripts/ast_grep_helper.py

A single-file Python 3 stdlib wrapper. Same on every OS. The agent's default entry point.

search — find all matches of a pattern

python3 scripts/ast_grep_helper.py search 'console.log($MSG)' --lang ts src/

Validates the pattern offline first. If the pattern looks like regex (\w, .*, |, etc.) the helper exits with a hint and never calls sg — saves a round-trip. Pass --force to skip validation.

Flags:

• --lang ts (or any of the 25 languages; aliases like js, py, rs, kt accepted)
• --globs '!**/*.test.ts' (repeatable; prefix ! to exclude)
• -C 3 (context lines)
• --json-out (raw JSON instead of human format)

replace — rewrite by pattern, dry-run by default

# Dry-run preview (default — no files mutated)
python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/

# Actually apply
python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/ --apply

The helper: 1. Validates both pattern and rewrite for hint-detectable mistakes. 2. Runs pass 1 with --json=compact to collect matches and show a preview. 3. If --apply is set, runs pass 2 with --update-all to mutate files.

scan — run YAML rules

# Discover sgconfig.yml from cwd and run all rules
python3 scripts/ast_grep_helper.py scan src/

# Run a single rule file
python3 scripts/ast_grep_helper.py scan -r rules/no-console.yml src/

# Apply auto-fixes
python3 scripts/ast_grep_helper.py scan -U src/

# CI-friendly GitHub annotations
python3 scripts/ast_grep_helper.py scan --report-style short src/

validate — offline pattern check (no sg call)

Useful for CI lints, pre-commit hooks, and quick sanity checks:

python3 scripts/ast_grep_helper.py validate '\w+' --lang ts
# → exit 2: regex \w not supported. Use $VAR for identifiers.

python3 scripts/ast_grep_helper.py validate 'console.log($MSG)' --lang ts
# → exit 0: pattern looks plausible for ast-grep.

langs / doctor / install

python3 scripts/ast_grep_helper.py langs       # list 25 supported languages and aliases
python3 scripts/ast_grep_helper.py doctor      # check ast-grep binary availability
python3 scripts/ast_grep_helper.py install     # delegate to install.sh / install.ps1

new and test subcommands proxy directly to sg new and sg test.

---

Direct sg use (when the helper isn't enough)

The helper is opinionated. For full control, drop to sg. The skill ships a CLI cheat sheet in references/cli.md. The minimal idioms:

# Search
sg run -p 'console.log($MSG)' --lang ts src/

# Search with JSON for scripting
sg run -p 'console.log($MSG)' --lang ts --json=compact src/ | jq '.[] | .file'

# Rewrite, dry-run
sg run -p 'console.log($MSG)' -r 'logger.info($MSG)' --lang ts --json=compact src/

# Rewrite, apply
sg run -p 'console.log($MSG)' -r 'logger.info($MSG)' --lang ts --update-all src/

# Pattern from stdin (great for ad-hoc experiments)
echo 'console.log("hi")' | sg run -p 'console.log($MSG)' --lang js --stdin

# Debug a pattern that returns 0 matches
sg run -p '<your pattern>' --lang <lang> --debug-query=ast --stdin <<< '<sample-code>'

# Run YAML rules
sg scan src/

# Inline YAML rule (one-off)
sg scan --inline-rules '
id: no-todo
language: TypeScript
severity: warning
rule: { pattern: TODO }' src/

When using sg directly in a shell, always single-quote patterns so $VAR is not expanded by the shell.

---

Decision tree — what to use, when

USER asks for "find/rewrite/codemod"
│
├─ structural pattern (function shape, call, class, import, control flow)
│  └→ ast-grep (this skill)
│
├─ text pattern (regex, alternation, character classes, file names)
│  └→ rg / grep
│
├─ semantic question (what variable does this refer to? does this throw?)
│  └→ LSP tools, TypeScript compiler, Pyright, Semgrep with type inference
│
└─ multiple repos / federated search
   └→ a search engine + then ast-grep / rg / LSP per-repo

If the user says "find all" or "every", default to ast-grep when the target is shaped (function, class, call, import, statement). Default to rg when the target is text (string content, comment, license header, file name, identifier substring).

---

Always run dry-run first when rewriting

A bad pattern silently rewrites the wrong thing. The helper's replace defaults to dry-run for this reason. The flow is:

1. Search to confirm matches: helper search '<pattern>' --lang X . 2. Dry-run rewrite: helper replace '<pattern>' '<rewrite>' --lang X . (no --apply) 3. Inspect the dry-run summary: number of matches, files affected, the per-location preview. 4. If wrong: refine pattern, go back to step 1. 5. If right: helper replace '<pattern>' '<rewrite>' --lang X . --apply.

Never apply a rewrite that you have not first dry-run.

---

When sg returns 0 matches but you know the code is there

In priority order:

1. Run `helper validate '<pattern>' --lang <lang>` — catches regex misuse, missing function bodies, Python trailing colons. 2. Check `--lang` — sg infers from extension; if you pass a .tsx file with --lang ts (not tsx), JSX won't parse. 3. Inspect the parsed pattern: sg run -p '<pattern>' --lang <lang> --debug-query=ast --stdin <<< '<sample>'. If it shows ERROR nodes, the pattern is malformed. 4. Check the AST of the target file: sg run -p '$_' --lang <lang> --debug-query=cst path/to/file | head -40 — find the kind you're trying to match. 5. Try the playground: <https://ast-grep.github.io/playground.html> — paste code + pattern, see what's happening.

Do not blindly retry with variations. Each failure has a reason; surface it.

---

When to use YAML rules vs inline -p patterns

Use inline `-p` when:

• One-off ad-hoc query.
• The pattern is simple (no constraints, no fix template).
• You're exploring.

Use YAML rules (file under rules/, run via sg scan) when:

• The pattern is reused (lint rule, codemod that runs in CI).
• You need constraints, transform, complex inside/has, or composite logic.
• You want auto-fix (fix: field).
• You want to test the rule (snapshot tests via sg test).

The full YAML rule schema is in references/yaml-rules.md. Project setup (sgconfig.yml, ruleDirs, utilDirs) is in references/sgconfig.md.

---

Output discipline

• sg run --json=compact produces an array of match objects: { file, range: {start, end}, text, replacement?, lines, language, ... }. Pipe through jq for further processing.
• Without --json, sg produces human-readable colored output suitable for terminals.
• The helper's default output is human-readable (file:line:column + match preview). Pass --json-out for raw JSON.
• The helper's replace always summarizes: number of matches, number of files, per-location preview.

When summarizing for the user, always include the count of files affected, not just the count of matches. Users care about blast radius.

---

Required reading (in order of priority)

1. references/patterns.md — meta-variables, naming rules, strictness levels. Read when you're unsure why a pattern doesn't match. 2. references/pitfalls.md — the failure-mode field guide. Read when 0 matches surprises you. 3. references/recipes.md — copy-paste patterns by language. Read first when you start a new task. 4. references/cli.md — sg run, sg scan, sg test, sg new, sg lsp. Read when the helper isn't enough. 5. references/yaml-rules.md — YAML rule schema. Read when you outgrow inline patterns. 6. references/sgconfig.md — project-level configuration. Read when you set up sg scan for a real project. 7. references/install.md — per-OS install methods. Read only if install.sh / install.ps1 fail.

---

Invariants (do not break)

• Validate before searching. When emitting a pattern programmatically, call helper validate first. It catches the regex-misuse class of mistakes that account for ~70% of "0 matches" debug sessions.
• Dry-run before applying. Never run sg run -r ... --update-all without first inspecting the matches. The helper's replace enforces this by default.
• Two-pass writes. When using sg directly to both preview and apply, run two invocations — --json ignores --update-all.
• Single-quote patterns in shell. '$VAR' not "$VAR". The shell expands $VAR to the empty string in double quotes, breaking the pattern.
• Pattern is code, not regex. When the pattern would need |, .*, \w, or [a-z], switch to rg instead. Don't try to force ast-grep into a regex shape.
• `--lang` is required for stdin. When piping with --stdin, set --lang explicitly; sg cannot infer from extension.
• Linux: prefer `ast-grep` over `sg` because sg collides with setgroups. The helper handles this; if you call sg directly, alias it: alias sg=ast-grep.

ast-grep-skill

LLM-neutral skill for AST-aware search and rewrite across 25 languages. Wraps the `ast-grep` (sg) CLI with offline pattern validation, the two-pass write trick, binary auto-resolution, and a per-OS installer.

Same shape as `web-fetch` and `web-search`, packaged as a standalone skill that any Bash-capable agent (Claude Code, OpenCode, pi, hermes, openclaw) can load.

Install

git clone https://github.com/code-yeongyu/ast-grep-skill ~/.agents/skills/ast-grep
bash ~/.agents/skills/ast-grep/install.sh        # installs the ast-grep binary

That is it. The wrapper script is single-file Python 3 stdlib; no pip install needed. The installer tries brew → npm → cargo → pip → nix → mise → GitHub release in priority order, picks the first that works, and falls back to a cached binary at <skill>/bin/sg.

Symlink for active development

ln -s /path/to/your/clone ~/.agents/skills/ast-grep

Other agents

• Claude Code / OpenCode: drop the directory under ~/.agents/skills/ (or ~/.config/opencode/skills/) and the skill auto-registers via the name + description in SKILL.md frontmatter.
• pi (`~/.senpi/agent`): not a pi extension — this is a skill. Pi consumes skills via ~/.agents/skills/ symlinks; the actual pi-ast-grep extension is at <https://github.com/code-yeongyu/pi-extensions>.
• Direct CLI use: python3 ~/.agents/skills/ast-grep/scripts/ast_grep_helper.py <subcommand>.

Usage

# Search by AST pattern (the helper validates patterns offline first)
python3 scripts/ast_grep_helper.py search 'console.log($MSG)' --lang ts src/

# Rewrite (dry-run preview by default)
python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/

# Apply the rewrite (two-pass: preview JSON + then --update-all)
python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/ --apply

# Run YAML lint rules from sgconfig.yml
python3 scripts/ast_grep_helper.py scan src/

# Validate a pattern OFFLINE (no sg call, no filesystem)
python3 scripts/ast_grep_helper.py validate '\w+' --lang ts
# → exit 2: regex \w not supported. Use $VAR for identifiers.

# Doctor: check ast-grep binary availability
python3 scripts/ast_grep_helper.py doctor

# List 25 supported languages
python3 scripts/ast_grep_helper.py langs

# Install / re-install the ast-grep binary
python3 scripts/ast_grep_helper.py install

See SKILL.md for full agent-facing usage and the `references/` directory for deep dives.

Project layout

ast-grep-skill/
├── SKILL.md                       agent-facing skill (loaded by Claude Code, OpenCode, pi, etc.)
├── README.md                      this file
├── LICENSE                        MIT
├── install.sh                     POSIX installer (macOS / Linux / WSL / Git Bash)
├── install.ps1                    Windows PowerShell installer
├── scripts/
│   └── ast_grep_helper.py         single-file Python 3 stdlib wrapper
├── references/
│   ├── install.md                 per-OS install methods + manual fallback
│   ├── patterns.md                meta-variables ($VAR, $$$) and pattern syntax
│   ├── pitfalls.md                regex anti-patterns + language-specific traps
│   ├── recipes.md                 copy-paste patterns by language (TS/JS/Py/Go/Rust/...)
│   ├── cli.md                     sg run / scan / test / new / lsp reference
│   ├── yaml-rules.md              YAML rule schema (atomic / relational / composite / transform / fix)
│   └── sgconfig.md                project configuration (ruleDirs, testConfigs, utilDirs)
├── tests/
│   ├── smoke.sh                   POSIX self-test
│   └── smoke.ps1                  PowerShell self-test (Windows CI)
└── .github/workflows/ci.yml       matrix CI: macos / ubuntu / windows × py 3.9-3.13

What it does

1. Wraps `sg` with a single Python 3 stdlib script that works the same on macOS, Linux, Windows, WSL, Git Bash. 2. Validates patterns offline before calling sg — catches the regex-misuse class of mistakes (\w, .*, |, [a-z]) plus language-specific traps (Python trailing colons, JS/Go/Rust missing function bodies). 3. Resolves the binary through 6 candidate paths: cached → PATH (with Linux setgroups collision detection) → Homebrew. Falls through to a clear install hint with copy-paste commands. 4. Runs the two-pass write trick when applying rewrites — sg run silently ignores --update-all when --json is set, so replace --apply runs two invocations: pass 1 collects JSON matches, pass 2 mutates files. 5. Ships per-OS installers that try every reasonable package manager and fall back to a GitHub release tarball. 6. Documents the failure modes the model will hit (regex misuse, incomplete patterns, --update-all + --json trap, scope/type questions ast-grep can't answer) in references/pitfalls.md.

What it does NOT do

• No type inference, scope analysis, or data flow. ast-grep is a structural matcher; for type-aware questions use TypeScript LSP, Pyright, Semgrep with type inference, or CodeQL.
• No multi-repo federation. Run the helper once per repo.
• No automatic sgconfig.yml discovery — it does what sg scan does (walk up from cwd looking for one).
• No JS/Python rewriter authoring environment — for that, write YAML rules and use sg test for snapshot testing (see `references/yaml-rules.md`).

Limits

• 5-minute timeout per sg invocation (configurable in the helper).
• ast-grep itself supports 25 languages out-of-the-box. For anything else, use `customLanguages` in sgconfig.yml.
• Pattern hint detection is heuristic; pass --force to skip validation when you know the pattern is correct.

Requirements

• Python ≥ 3.9 (stdlib only — no pip install).
• ast-grep binary, installed via install.sh / install.ps1 or one of:
• brew install ast-grep (macOS / linuxbrew)
• npm install -g @ast-grep/cli (any OS with Node)
• cargo install ast-grep --locked (any OS with Rust)
• pip install ast-grep-cli (any OS with Python)
• scoop install main/ast-grep (Windows)

For older systems and Windows-specific setup, see `references/install.md`.

Testing

bash tests/smoke.sh        # POSIX (macOS / Linux / WSL / Git Bash)
pwsh tests/smoke.ps1       # Windows (PowerShell 5.1+ or 7+)

CI runs the matrix on every push: {macos-latest, ubuntu-latest, ubuntu-22.04, windows-latest} × {Python 3.9, 3.10, 3.11, 3.12, 3.13} plus a syntax-floor check on Python 3.9 and 3.10.

License

MIT.

Acknowledgments

• `omo` (oh-my-opencode) — src/tools/ast-grep/ is the original tool implementation; this skill is a port of its pattern-hint detection and two-pass-write strategy.
• `pi-extensions/pi-ast-grep` — sibling Node port; the helper's binary-resolution cascade is modelled on it.
• ast-grep — the CLI. All structural matching power comes from it.
• Anthropic skills — the SKILL.md + references/ packaging convention.

CLI reference — sg / ast-grep

Compact reference for the underlying sg binary that the helper wraps. Use this when the helper isn't enough or when you want to invoke sg directly.

Binary name on Linux: prefer ast-grep over sg because sg collides with setgroups from util-linux.

---

sg run — one-shot search/rewrite

The default subcommand. sg -p 'foo' is shorthand for sg run -p 'foo'.

sg run [OPTIONS] --pattern <PATTERN> [PATHS...]

--update-all + --json — the trap

sg silently ignores --update-all when --json is set. To preview AND apply, run two passes:

# Pass 1: preview
sg run -p 'foo()' -r 'bar()' --json=compact src/

# Pass 2: apply
sg run -p 'foo()' -r 'bar()' --update-all src/

The ast_grep_helper.py replace --apply subcommand does this automatically.

Examples

# Basic search
sg run -p 'console.log($MSG)' --lang ts src/

# Search with context lines
sg run -p 'eval($CODE)' --lang js -C 3 .

# Rewrite, dry-run preview as JSON
sg run -p 'console.log($MSG)' -r 'logger.info($MSG)' --json=compact --lang ts src/

# Rewrite, apply
sg run -p 'console.log($MSG)' -r 'logger.info($MSG)' --update-all --lang ts src/

# Pattern from stdin
echo 'console.log("x")' | sg run -p 'console.log($MSG)' --lang js --stdin

# Limit to specific files
sg run -p 'foo()' --lang ts --globs 'src/**/*.ts' --globs '!**/*.test.ts' .

# Debug a pattern that returns 0 matches
sg run -p 'def $F($$$):' --lang py --debug-query=ast --stdin <<< 'def foo(): pass'

---

sg scan — YAML rule scanner

Run a configuration of YAML rules across files. Used for project-wide lints and codemods.

sg scan [OPTIONS] [PATHS...]

Examples

# Run all rules in sgconfig.yml-discovered ruleDirs
sg scan src/

# Run a single rule file (no sgconfig.yml needed)
sg scan -r rules/no-console.yml src/

# Inline rule (great for one-offs and CI)
sg scan --inline-rules '
id: no-todo
language: TypeScript
severity: warning
rule: { pattern: TODO }' src/

# Apply all auto-fixes
sg scan -U src/

# CI-friendly GitHub annotations
sg scan --format github src/

# SARIF for security scanners
sg scan --format sarif src/ > sarif.json

---

sg test — run rule snapshot tests

sg test [OPTIONS]

A test directory looks like:

test/
├── no-console.yml          # `valid:` and `invalid:` snippets
└── no-console-test.yml     # alternative test file format
__snapshots__/
└── no-console-snapshot.yml # expected match locations

---

sg new — scaffold

sg new <COMMAND> [NAME] [OPTIONS]

# New project in current dir
sg new project --yes

# New rule
sg new rule no-console --lang typescript

# New test
sg new test no-console --yes

---

sg lsp — language server

sg lsp -c sgconfig.yml

Speak LSP over stdin/stdout. Configure your editor (VS Code extension, Neovim nvim-lspconfig, Helix languages.toml) to spawn this command for live diagnostics.

---

sg completions — shell completions

sg completions bash >> ~/.bashrc
sg completions zsh > "${fpath[1]}/_sg"
sg completions fish > ~/.config/fish/completions/sg.fish
sg completions powershell >> $PROFILE

---

Useful one-liners

# Count matches per file
sg run -p 'console.log($_)' --lang ts --json=compact . \
  | jq -r '.[].file' | sort | uniq -c | sort -rn

# Find all unique kinds in a file (great for figuring out kind names)
sg run -p '$_' --lang ts --debug-query=cst src/foo.ts \
  | grep -oE 'kind: [a-z_]+' | sort -u

# Rewrite only in a subset of files
sg run -p 'foo()' -r 'bar()' --update-all --globs 'src/**/*.ts' --globs '!src/legacy/**' .

# Apply fixes from many rules but only ones matching a pattern in their id
sg scan --filter 'no-' -U src/

# Use ast-grep as a linter in pre-commit
sg scan --format github src/ || exit 1

---

See also

• references/yaml-rules.md — rule schema (pattern, kind, regex, inside, has, all, any, not, matches, transform, fix).
• references/sgconfig.md — project configuration.
• Official: <https://ast-grep.github.io/reference/cli.html>

Install ast-grep

The skill ships an install.sh (POSIX) and install.ps1 (Windows) that try every reasonable method in priority order and fall back to a GitHub release download as a last resort. You usually do not need to read this page. Run the installer:

bash install.sh                        # macOS / Linux / WSL / Git Bash
pwsh -File install.ps1                 # Windows PowerShell

This page exists for the (rare) case the installer cannot find a working method, or you want to install ast-grep manually.

---

Per-OS install commands (verbatim, copy-paste)

macOS

brew install ast-grep                  # Homebrew - the primary path
sudo port install ast-grep             # MacPorts
npm install -g @ast-grep/cli           # if you have Node already
cargo install ast-grep --locked        # if you have Rust already

Linux

# Universal (works on every distro)
npm install -g @ast-grep/cli
cargo install ast-grep --locked
pip install ast-grep-cli

# Distro-specific
nix-env -iA nixpkgs.ast-grep           # NixOS / Nix
brew install ast-grep                  # Linuxbrew

# NixOS shell.nix
nix-shell -p ast-grep

Linux gotcha: the binary is named sg, but on most Linux systems sg is also the `setgroups` command from util-linux. The shell sees setgroups first and ignores ast-grep. Two options:

>

1. Always invoke ast-grep (full name).

2. Add an alias: alias sg=ast-grep in your ~/.bashrc / ~/.zshrc.

>

The ast_grep_helper.py script in scripts/ already handles this — when it sees sg on PATH on Linux, it runs --version and rejects the binary if it isn't ast-grep.

Windows

scoop install main/ast-grep            # Scoop (most common on dev machines)
winget install --id ast-grep.ast-grep  # Winget (Microsoft built-in)
choco install ast-grep                 # Chocolatey
npm install -g @ast-grep/cli           # any OS with Node
cargo install ast-grep --locked        # any OS with Rust

WSL / Git Bash on Windows

Treat as Linux. Use npm, cargo, pip, or bash install.sh.

---

Cross-platform / language-ecosystem methods

These work on every OS:

---

GitHub release manual install

If every package manager fails:

# 1. Pick the right asset for your OS+arch from the latest release:
#    https://github.com/ast-grep/ast-grep/releases/latest
#
#    Naming pattern:
#      ast-grep-aarch64-apple-darwin.zip          macOS Apple Silicon
#      ast-grep-x86_64-apple-darwin.zip           macOS Intel
#      ast-grep-aarch64-unknown-linux-gnu.zip     Linux ARM64 (glibc)
#      ast-grep-x86_64-unknown-linux-gnu.zip      Linux x86_64 (glibc)
#      ast-grep-x86_64-unknown-linux-musl.zip     Linux x86_64 (musl, e.g. Alpine)
#      ast-grep-x86_64-pc-windows-msvc.zip        Windows x86_64
#      ast-grep-aarch64-pc-windows-msvc.zip       Windows ARM64

# 2. Download and extract:
VERSION=0.42.1
TRIPLE=aarch64-apple-darwin
curl -fsSL "https://github.com/ast-grep/ast-grep/releases/download/${VERSION}/ast-grep-${TRIPLE}.zip" -o /tmp/ast-grep.zip
unzip /tmp/ast-grep.zip -d /tmp/ast-grep
sudo mv /tmp/ast-grep/ast-grep /usr/local/bin/sg
sudo chmod +x /usr/local/bin/sg

# 3. Verify:
sg --version

The skill's install.sh does steps 1-3 automatically and drops the binary in <skill_root>/bin/sg so you can use it without sudo.

---

Build from source

git clone https://github.com/ast-grep/ast-grep.git
cd ast-grep
cargo install --path ./crates/cli --locked

Requires Rust 1.74+. Slowest path; only useful when you need a specific commit or unreleased fix.

---

Verifying the install

ast-grep --version            # or `sg --version`
# ast-grep 0.42.1

Then sanity-check a real query:

echo 'console.log("hello")' | sg run -p 'console.log($MSG)' --lang js --stdin

Expected: a single match with the console.log("hello") call highlighted.

---

Editor integration

After installing the CLI, set up your editor:

• VS Code: install the `ast-grep` extension. Requires sgconfig.yml in workspace root for live diagnostics.
• Neovim: configure nvim-lspconfig with ast_grep server, or install `telescope-ast-grep.nvim`.
• Helix: add ast-grep lsp as a language server in languages.toml.
• Emacs: install `ast-grep.el`.

See references/cli.md for ast-grep lsp flags.

---

Uninstall

Pattern syntax — meta-variables and how patterns parse

ast-grep is not regex. Patterns are written in the same syntax as the target language (TypeScript, Python, Go, etc.), and ast-grep matches them against the AST of every file. The wildcards are called meta-variables.

This page is the canonical primer. If a pattern fails, 90% of the time it is one of the issues on this page.

---

The three meta-variables

A meta-variable always replaces a whole AST node, never a substring of a node. $VAR cannot match the first three characters of an identifier, only an entire identifier (or expression, or statement, depending on context).

Naming rules

• Must start with $.
• Then uppercase letters A-Z, digits, or underscores.
• Valid: $X, $VAR, $VAR_1, $_, $_VAR, $ARG1.
• Invalid: $lower, $kebab-case, $1 (digit first), $$single (use $_ for anonymous).

Same-name = same content

Two occurrences of the same metavariable in a pattern must capture identical text:

// Pattern
$X === $X

// Matches
a === a
foo.bar === foo.bar

// Does NOT match
a === b
foo === foo.bar

Useful for finding redundant comparisons, double assignments, etc.

$$$ is lazy

When you write foo($$$A, b, $$$C), the matcher does not try every possible split. It greedily fills $$$A until the pattern can match b, then everything left goes into $$$C.

// Pattern
foo($$$A, b, $$$C)

// Input
foo(a, c, b, b, c)

// Capture
$$$A = [a, c]
$$$C = [b, c]

If you need a different split, restructure the pattern (e.g. add a constraint).

---

Patterns must be valid code

The pattern itself must parse with the target language's grammar. ast-grep treats $VAR and $$$ as identifiers/argument lists during parsing, then matches structurally.

What goes wrong

When a sub-expression isn't valid on its own

Sometimes you want to match an expression that the language only allows inside a larger context. Use the pattern object form:

pattern:
  context: 'class A { $FIELD = $INIT }'
  selector: field_definition

This says: parse class A { $FIELD = $INIT } as a whole, then keep only the field_definition sub-tree as the actual pattern.

---

Strictness levels

When CST nodes don't match exactly (extra whitespace, different unnamed punctuation), ast-grep can be more or less forgiving. Pass --strictness <LEVEL> on the CLI, or set it in a YAML rule:

smart is almost always what you want. Reach for signature when you want to match "any function called foo" regardless of arguments.

---

Testing a pattern

Two tools help you confirm a pattern parses the way you expect:

# Print the AST of the pattern itself
sg run -p 'console.log($MSG)' --lang ts --debug-query=ast

# Print the parsed CST of a file (great for figuring out kind names)
sg run -p '$_' --lang ts --debug-query=cst src/example.ts | head -40

--debug-query=ast shows the named AST nodes only (cleaner). --debug-query=cst shows everything including punctuation. Both go to stderr, so they don't interfere with stdout JSON.

The web playground is also fast: <https://ast-grep.github.io/playground.html>.

---

When ast-grep is the wrong tool

If your pattern is fundamentally text-shaped, switch to grep / rg:

• Match across multiple files for any text → rg
• Cross-language regex with alternation → rg -e foo -e bar
• Match comments only → rg --type ts '^\s*//.*TODO'
• Match URLs, emails, license headers → rg

ast-grep is for code structure: function shapes, call patterns, control flow, type annotations, imports, error handling. If your "pattern" only depends on the bytes of the file and not on the syntax, regex is the right tool.

---

See also

• references/pitfalls.md — concrete regex anti-patterns and language-specific traps.
• references/recipes.md — copy-paste-ready patterns for TS/JS/Py/Go/Rust.
• references/yaml-rules.md — kind, regex, inside, has, all, any, not, matches.
• Official: <https://ast-grep.github.io/guide/pattern-syntax.html>

Pitfalls — what breaks patterns and how to fix them

This is the failure-mode field guide. The scripts/ast_grep_helper.py validate subcommand mechanically checks for the items in §1 before calling sg; the rest are lower-frequency but still common.

---

1. Regex syntax does not work

ast-grep does not interpret regex inside patterns. The following all fail:

Why this happens: LLMs default to regex thinking. The mental switch is "ast-grep patterns are code, not strings."

When you genuinely need regex, use the regex rule field in YAML (matches node text with Rust regex):

rule:
  all:
    - kind: identifier
    - regex: '^[A-Z][a-z]+$'   # CamelCase identifiers only

Note: regex matches the whole node text — no partial matches. Combine with kind or pattern for performance.

---

2. Incomplete AST nodes

Patterns must be valid code that the parser accepts as a complete node. Common mistakes:

# JS/TS
function foo                              ❌ no params, no body
function $NAME($$$) { $$$ }               ✅

async function $NAME                      ❌
async function $NAME($$$) { $$$ }         ✅

# Python
def foo:                                  ❌ trailing colon makes it a statement
def $FN($$$)                              ✅
class Foo:                                ❌
class $C($$$)                             ✅

# Go
func foo                                  ❌
func $NAME($$$) { $$$ }                   ✅

# Rust
fn foo                                    ❌
fn $NAME($$$) -> $RET { $$$ }             ✅
fn $NAME($$$) { $$$ }                     ✅ (-> () inferred)

# Java
public void foo                           ❌
public void $NAME($$$) { $$$ }            ✅

If a pattern returns 0 matches and looks correct, run sg run -p '<pattern>' --lang <lang> --debug-query=ast --stdin <<< 'echo' and see what the parser thinks the pattern is. If it returns an ERROR node, the pattern is malformed.

---

3. Pattern parses as the wrong kind

A class field initializer a = 123 also parses as an assignment expression. If you want only field definitions, you must disambiguate:

# WRONG — pattern parses as assignment_expression, not field_definition
pattern: a = 123
kind: field_definition

# CORRECT — use pattern object with context + selector
pattern:
  context: 'class C { a = 123 }'
  selector: field_definition

kind and pattern are independent constraints, not modifiers of each other. ast-grep does not change how it parses based on kind.

---

4. The | ambiguity

A bare | in a pattern is interpreted as bitwise-or in most languages, not alternation. So:

pattern: foo | bar          # parses as: foo bitwise-or'd with bar

…matches expressions like x | y, not "either foo or bar". To get alternation, use any:

rule:
  any:
    - pattern: foo
    - pattern: bar

In TypeScript union types (A | B), | is part of the type syntax — pattern: A | B correctly parses as a union type and matches that.

---

5. Same-name metavars collide

// Pattern: $X = $X
// Captures only when both sides are TEXTUALLY identical.

// Matches:
a = a
foo.bar = foo.bar

// Does NOT match:
a = b
let x = compute()      // because $X needs to bind once and re-use

If you actually want two independent captures, name them differently: $X = $Y.

---

6. $$$ is greedy then commits

$$$ does not backtrack. It captures as much as possible, then commits. If your pattern needs a non-greedy match, structure it differently:

// You want "match foo($X), where $X is any single arg"
// BAD:  foo($$$X)        // matches foo(a), foo(a, b), foo(a, b, c) - too broad
// GOOD: foo($X)          // matches only single-arg calls

// You want "match foo() with at least one arg"
// BAD:  foo($$$X)        // also matches foo()
// GOOD: foo($X, $$$REST) // forces at least one arg

---

7. kind names depend on tree-sitter grammar

kind: function_declaration works for JavaScript, but Python uses function_definition, Rust uses function_item, Go uses function_declaration (same as JS by coincidence). To find the right name, parse a known-good file:

sg run -p '$_' --lang python --debug-query=cst path/to/example.py | grep -i function

Or open <https://ast-grep.github.io/playground.html> and click on a node to see its kind.

---

8. inside / has defaults to stopBy: neighbor

inside:
  kind: function_declaration   # only checks the IMMEDIATE parent

If you want "anywhere inside a function (any depth)":

inside:
  kind: function_declaration
  stopBy: end                  # walks up to the file root

Same for has (descendants):

has:
  kind: return_statement
  stopBy: end                  # walks down the whole subtree

Without stopBy: end, has only matches direct children.

---

9. CLI silently ignores --update-all when --json is set

This is the single biggest gotcha when scripting ast-grep. If you run:

sg run -p 'foo()' -r 'bar()' --json=compact --update-all .

…you get the JSON output but no files are mutated. ast-grep silently drops --update-all when --json is on. To both preview and apply, run two passes:

# Pass 1: preview as JSON
sg run -p 'foo()' -r 'bar()' --json=compact .

# Pass 2: actually apply
sg run -p 'foo()' -r 'bar()' --update-all .

scripts/ast_grep_helper.py replace does this automatically when --apply is set.

---

10. Composite rules apply to a single node

all and any evaluate against one target node at a time:

# WRONG — wants "node has BOTH a number child AND a string child"
has:
  all:
    - kind: number       # impossible: one node cannot be both at once
    - kind: string

# CORRECT
all:
  - has: { kind: number }
  - has: { kind: string }

Lift relational rules out of composites when the relation is "the surrounding node has X children matching Y."

---

11. Field order is not guaranteed

When a rule object has multiple fields:

rule:
  pattern: $X = compute()
  has: { kind: number }

…ast-grep evaluates them as an implicit all, but the order in which metavariables are captured is not guaranteed. If your transform or fix depends on capture order, use an explicit all array:

rule:
  all:
    - pattern: function $F() { $$$ }
    - has: { pattern: $F() }     # $F captured by pattern first; here we just check

---

12. regex without kind is slow

regex alone scans every node text in the file. On large repos this is noticeably slow. Always combine:

# Slow
rule:
  regex: '^TODO'

# Fast
rule:
  all:
    - kind: comment
    - regex: '^//\s*TODO'

---

13. No scope / type / data-flow analysis

ast-grep is a structural matcher. It does NOT know:

• Whether two foo references point to the same variable.
• Whether a variable is shadowed.
• Whether a function is async, throws, returns a Promise.
• Whether a value flows from input to output.

For those questions, use a real type-aware tool: TypeScript LSP, Pyright, Semgrep with type inference, CodeQL, etc.

ast-grep is great when the syntactic shape is what you care about: "find every call to eval(...)", "find every as any", "find every empty catch block." It is weak for "find every variable that's never used."

---

14. Pattern testing is the fastest debugger

When a pattern returns 0 matches and you can't see why:

1. Open <https://ast-grep.github.io/playground.html>. 2. Paste your code into the left pane, your pattern into the top-right. 3. The bottom-right shows the parsed AST and which nodes matched (highlighted) or failed.

Or locally:

sg run -p '<pattern>' --lang <lang> --debug-query=ast --stdin <<< '<sample-code>'

stderr shows the parsed pattern; stdout shows the JSON match result. If the pattern shows up as ERROR (XXX), it doesn't parse.

---

See also

• references/patterns.md — meta-variables, strictness, naming rules.
• references/recipes.md — known-good patterns by language.
• references/cli.md — --debug-query, --strictness, --update-all.

Recipes — copy-paste patterns by language

Every pattern in this file has been verified against the canonical syntax. They are starting points; tweak metavariable names and constraints to fit your case.

Use them with the helper:

ast-grep-helper search '<PATTERN>' --lang <LANG> [path]
ast-grep-helper replace '<PATTERN>' '<REWRITE>' --lang <LANG> [path]   # dry-run
ast-grep-helper replace '<PATTERN>' '<REWRITE>' --lang <LANG> [path] --apply

Or directly:

sg run -p '<PATTERN>' --lang <LANG> [path]
sg run -p '<PATTERN>' -r '<REWRITE>' --update-all --lang <LANG> [path]

---

TypeScript / TSX / JavaScript

Find structural patterns

// Every function declaration
function $NAME($$$PARAMS) { $$$BODY }

// Every async function
async function $NAME($$$PARAMS) { $$$BODY }

// Every arrow function (any param shape)
($$$PARAMS) => $$$BODY

// Every method on a class
class $C { $$$ $METHOD($$$P) { $$$B } $$$ }

// Every import statement
import { $$$NAMES } from '$MOD'
import $DEFAULT from '$MOD'
import * as $NS from '$MOD'

// Every console.* call
console.$METHOD($$$ARGS)

// Every JSX element of a given name
<MyComponent $$$PROPS>$$$CHILDREN</MyComponent>

// Every try/catch
try { $$$BODY } catch ($E) { $$$HANDLER }

// Every throw
throw $EXPR

// Every new expression
new $CLASS($$$ARGS)

// Every type assertion to any (anti-pattern!)
$EXPR as any
$EXPR as unknown as $T

Common rewrites

# console.log -> logger.info
sg run -p 'console.log($$$A)' -r 'logger.info($$$A)' --lang ts --update-all .

# require -> import (one-arg case)
sg run -p 'const $V = require($M)' -r 'import $V from $M' --lang ts --update-all .

# .then(callback) -> await on the same line (use with caution; needs async function context)
sg run -p '$P.then($CB)' -r 'const $TMP = await $P; $CB($TMP)' --lang ts --update-all .

# Strip `as any`
sg run -p '$E as any' -r '$E' --lang ts --update-all .

# Rename a function call site
sg run -p 'oldName($$$A)' -r 'newName($$$A)' --lang ts --update-all .

---

Python

Reminder: never end a Python pattern with :. Patterns parse as a complete statement, so def foo($$$): is invalid.

# Every function definition
def $FN($$$PARAMS)

# Every class definition
class $C($$$BASES)

# Every decorator usage
@$DEC
def $FN($$$P)

# Every print call (Python 3)
print($$$ARGS)

# Every f-string
f"$STR"

# Every with-statement
with $CTX as $VAR: $$$BODY

# Every try/except
try: $$$BODY
except $EXC: $$$HANDLER

# Every list comprehension
[$EXPR for $VAR in $ITER]

# Every async def
async def $FN($$$PARAMS)

# Type hints — Optional[X]
Optional[$T]

# Type hints — X | None (PEP 604)
$T | None

Common rewrites

# print(...) -> logger.info(...)
sg run -p 'print($$$A)' -r 'logger.info($$$A)' --lang py --update-all .

# Optional[X] -> X | None
sg run -p 'Optional[$T]' -r '$T | None' --lang py --update-all .

# from typing import List -> remove (built-in list works in 3.9+)
sg run -p 'from typing import List' -r 'from typing import List  # TODO: remove, use list' --lang py --update-all .

---

Go

// Every function
func $NAME($$$PARAMS) $$$RET { $$$BODY }

// Every method
func ($RECV $TYPE) $NAME($$$PARAMS) $$$RET { $$$BODY }

// The classic err nil-check
if err != nil { $$$BODY }

// Every fmt.Println / fmt.Printf / fmt.Sprintf
fmt.$METHOD($$$ARGS)

// Every defer
defer $EXPR

// Every goroutine
go $EXPR

// Every channel send/recv
$CH <- $VAL
$VAL := <-$CH

// Every type assertion
$EXPR.($TYPE)

Common rewrites

# fmt.Println -> log.Println
sg run -p 'fmt.Println($$$A)' -r 'log.Println($$$A)' --lang go --update-all .

# Add error wrapping
sg run -p 'return $ERR' -r 'return fmt.Errorf("operation failed: %w", $ERR)' --lang go --update-all .

---

Rust

// Every fn
fn $NAME($$$PARAMS) -> $RET { $$$BODY }
fn $NAME($$$PARAMS) { $$$BODY }       // no return type

// Every async fn
async fn $NAME($$$PARAMS) -> $RET { $$$BODY }

// Every method on impl
impl $TYPE { fn $METHOD($$$P) -> $R { $$$B } }

// Every trait impl
impl $TRAIT for $TYPE { $$$ITEMS }

// Every match expression
match $EXPR { $$$ARMS }

// Every Result-returning fn that uses ?
fn $N($$$P) -> Result<$T, $E> { $$$ }

// .unwrap() / .expect() (anti-patterns)
$EXPR.unwrap()
$EXPR.expect($MSG)

// Every println!/eprintln!/format!
println!($$$ARGS)
format!($$$ARGS)

Common rewrites

# unwrap() -> ? in Result-returning fns (caution: needs context)
sg run -p '$E.unwrap()' -r '$E?' --lang rust --update-all .

# eprintln! -> log::error!
sg run -p 'eprintln!($$$A)' -r 'log::error!($$$A)' --lang rust --update-all .

---

Java

// Every public class
public class $NAME { $$$BODY }

// Every method (any modifier)
$$$MOD $RET $NAME($$$P) { $$$BODY }

// Every System.out.println / System.err.println
System.$STREAM.println($$$ARGS)

// Every try-with-resources
try ($$$RES) { $$$BODY } catch ($EXC $E) { $$$HANDLER }

// Every annotation usage
@$ANNOTATION
$DECL

---

C / C++

// Every printf-family call
printf($$$ARGS)
sprintf($$$ARGS)
fprintf($$$ARGS)

// Every malloc / free pair (find-only — pairing requires data flow)
malloc($SIZE)
free($PTR)

// Every for-loop
for ($INIT; $COND; $POST) { $$$BODY }

// C++ smart pointer make
std::make_shared<$T>($$$ARGS)
std::make_unique<$T>($$$ARGS)

Rewrites

# malloc(N * sizeof(T)) -> calloc(N, sizeof(T)) - safer
sg run -p 'malloc($N * sizeof($T))' -r 'calloc($N, sizeof($T))' --lang c --update-all .

---

CSS

/* Every rule with a specific property */
{ $$$ color: $VAL; $$$ }

/* Every @media query */
@media $QUERY { $$$BODY }

/* Every var() reference */
var($NAME)

---

HTML

<!-- Every img without alt -->
<img $$$ />

<!-- Every script tag -->
<script $$$>$$$BODY</script>

<!-- Every link to stylesheet -->
<link rel="stylesheet" href=$URL />

---

Bash / Shell

# Every for-loop
for $VAR in $$$LIST; do $$$BODY; done

# Every if-statement
if $$$COND; then $$$BODY; fi

# Every function definition
$NAME() { $$$BODY }

# Every subshell call
$( $$$CMD )

---

YAML rule recipes (for sg scan)

These are full YAML rules you can drop in rules/*.yml and run via sg scan. See references/yaml-rules.md for the full schema.

no-console (TypeScript)

id: no-console
language: TypeScript
severity: warning
message: "Avoid console.* in production"
rule:
  pattern: console.$METHOD($$$ARGS)
fix: logger.$METHOD($$$ARGS)

no-as-any (TypeScript)

id: no-as-any
language: TypeScript
severity: error
message: "`as any` defeats type safety. Use a proper type."
rule:
  pattern: $EXPR as any
fix: $EXPR

empty-catch (JavaScript)

id: empty-catch
language: JavaScript
severity: error
message: "Empty catch swallows errors silently."
rule:
  all:
    - pattern: try { $$$T } catch ($E) { $$$H }
    - has:
        kind: catch_clause
        has:
          kind: statement_block
          not:
            has:
              kind: statement
              stopBy: end

print-to-logger (Python)

id: print-to-logger
language: Python
severity: hint
message: "Use logger.info instead of print"
rule:
  pattern: print($$$ARGS)
fix: logger.info($$$ARGS)

no-unwrap (Rust)

id: no-unwrap
language: Rust
severity: warning
message: "Avoid .unwrap() in production code; propagate or handle the error."
rule:
  pattern: $EXPR.unwrap()

---

See also

• references/patterns.md — meta-variable rules.
• references/yaml-rules.md — full YAML rule schema (atomic / relational / composite / transform / fix).
• references/cli.md — sg run, sg scan, sg test, sg new.
• Official catalog: <https://ast-grep.github.io/catalog/> (community-maintained, browse by language).

sgconfig.yml — project configuration

sgconfig.yml lives at your project root (the same place as package.json, Cargo.toml, pyproject.toml, etc.) and tells sg scan/sg test where to find rules and tests.

sg walks upward from the current directory until it finds an sgconfig.yml. You can also pass --config <path> explicitly.

---

Minimal project layout

my-project/
├── sgconfig.yml
├── rules/
│   ├── no-console.yml
│   └── no-as-any.yml
├── utils/
│   └── is-literal.yml
├── tests/
│   ├── no-console.yml
│   └── __snapshots__/
│       └── no-console-snapshot.yml
└── src/
    └── ...

# sgconfig.yml
ruleDirs:
  - rules

testConfigs:
  - testDir: tests
    snapshotDir: __snapshots__

utilDirs:
  - utils

That's it. sg scan src/ will load every .yml in rules/, find every .ts/.py/whatever matching the rule's language, and report violations.

---

Full schema

# Rule directories — required
ruleDirs:
  - rules
  - team-rules
  - vendor/sg-rules

# Test directories — optional
testConfigs:
  - testDir: tests
    snapshotDir: __snapshots__
  - testDir: integration-tests

# Utility rule directories — optional
# Files here become global utilities accessible via `matches: <id>` from any rule.
utilDirs:
  - utils
  - team-utils

# Override file-extension -> language mapping — optional
# Useful when your code uses non-standard extensions.
languageGlobs:
  html:
    - '*.vue'
    - '*.svelte'
    - '*.astro'
  json:
    - '.eslintrc'
    - '.prettierrc'
  cpp:
    - '*.c'                  # treat C as C++
  tsx:
    - '*.ts'                 # treat all .ts as TSX (so TSX rules work everywhere)

# Custom tree-sitter languages (experimental) — optional
customLanguages:
  mojo:
    libraryPath: tree-sitter-mojo.so
    extensions: [mojo, '🔥']
    expandoChar: _           # Replace $ in patterns when language uses $ syntactically
    languageSymbol: tree_sitter_mojo

# Language injection — embedded code in another language (experimental) — optional
# Example: CSS inside styled-components template literals.
languageInjections:
  - hostLanguage: js
    rule:
      pattern: 'styled.$TAG`$CONTENT`'
    injected: css

---

Field-by-field

ruleDirs (required)

Array<string> — directories containing rule YAML files. Resolved relative to sgconfig.yml.

Each .yml/.yaml file in these directories is loaded as a rule. One file can contain multiple rules separated by ---.

testConfigs

Array<TestConfig> where each entry has:

• testDir (required): directory of test YAML files.
• snapshotDir (optional, default __snapshots__): directory for snapshots.

Each test file looks like:

id: no-console
valid:
  - 'logger.info("hi")'
invalid:
  - 'console.log("hi")'

sg test runs every test, compares matches against the snapshot, and fails on diff. Snapshots are created on first run with -U.

utilDirs

Array<string> — directories with global utility rules. Each util file must have id and language. Utils become referenceable via matches: <id> from any rule in the project.

languageGlobs

HashMap<string, Array<string>> — override which extensions map to which language. Takes precedence over the built-in defaults.

Useful for:

• Custom file extensions (.eslintrc is JSON).
• Force-treating .ts files as TSX (so JSX-shaped patterns work).
• Vue/Svelte/Astro files (HTML host language).

customLanguages (experimental)

Register a tree-sitter parser that ast-grep doesn't ship with. Requires:

• libraryPath: path to a built .so / .dylib / .dll containing the grammar.
• extensions: file extensions to recognize.
• languageSymbol: the C symbol exported by the grammar (typically tree_sitter_<name>).
• expandoChar (optional): character to substitute for $ in patterns when the host language uses $ syntactically (PHP, jQuery, etc.).

This is rarely needed — ast-grep already supports 25 languages out of the box.

languageInjections (experimental)

Match patterns inside embedded languages. Example: CSS inside JS template literals (styled-components, emotion).

languageInjections:
  - hostLanguage: js
    rule:
      pattern: 'styled.$TAG`$CONTENT`'
    injected: css

After this, a css rule with pattern color: $C will match $CONTENT strings.

---

Common configurations

Monorepo with shared rules

monorepo/
├── sgconfig.yml          # root config — applies to entire monorepo
├── shared-rules/
│   ├── no-todo.yml
│   └── no-as-any.yml
└── packages/
    ├── frontend/
    │   ├── sgconfig.yml  # extends root with frontend-specific rules
    │   └── rules/
    └── backend/
        ├── sgconfig.yml  # extends root with backend-specific rules
        └── rules/

Each package's sgconfig.yml references both the package-local rules and the shared ones:

# packages/frontend/sgconfig.yml
ruleDirs:
  - rules
  - ../../shared-rules

Single rule file (no project)

For one-offs, skip sgconfig.yml entirely:

sg scan -r path/to/single-rule.yml src/

Inline rule (no file)

sg scan --inline-rules '
id: no-todo
language: TypeScript
severity: warning
rule: { pattern: TODO }' src/

Multiple rules separated by ---:

sg scan --inline-rules '
id: no-todo
language: TypeScript
rule: { pattern: TODO }
---
id: no-fixme
language: TypeScript
rule: { pattern: FIXME }' src/

---

Editor integration

VS Code / Neovim / Helix detect sgconfig.yml automatically and surface diagnostics from every rule. Without sgconfig.yml, the LSP runs without any rules loaded.

To enable schema validation in your editor, add a header to each rule file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/ast-grep/ast-grep/main/schemas/rule.json
id: no-console
language: TypeScript
rule:
  pattern: console.log($_)

---

See also

• references/yaml-rules.md — rule schema (atomic / relational / composite / transform / fix).
• references/cli.md — sg scan, sg test, sg new project.
• Official: <https://ast-grep.github.io/reference/sgconfig.html>, <https://ast-grep.github.io/guide/project/project-config.html>

YAML rule reference — atomic, relational, composite, transform, fix

Use this when you outgrow inline sg run -p ... patterns and need a reusable, testable rule. A YAML rule is the unit of work for sg scan. Drop one or more files in ruleDirs/ (configured via sgconfig.yml) and they get loaded automatically.

This page is the practical reference. The full upstream docs live at:

• <https://ast-grep.github.io/reference/yaml.html>
• <https://ast-grep.github.io/reference/rule.html>
• <https://ast-grep.github.io/cheatsheet/rule.html>

---

Skeleton

A single YAML file can hold multiple rules separated by ---.

id: no-console
language: TypeScript
severity: warning
message: "Avoid console.* in production"
note: |
  Use a proper logger so we can route logs to stderr in production
  and silence them in tests.
url: https://internal.docs/rules/no-console

rule:
  pattern: console.$METHOD($$$ARGS)

fix: logger.$METHOD($$$ARGS)

constraints:
  METHOD:
    not:
      regex: '^(error|warn)$'

files:
  - 'src/**/*.ts'
ignores:
  - 'src/**/*.test.ts'

metadata:
  category: logging

---

Top-level fields

---

Atomic rules — match a single node

pattern

Match by structural pattern. The most common rule.

# String form
rule:
  pattern: console.log($MSG)

# Object form (when context is needed)
rule:
  pattern:
    context: 'class C { $FIELD = $INIT }'
    selector: field_definition
    strictness: relaxed   # optional, default: smart

kind

Match by AST node type name. Tree-sitter grammar-specific.

rule:
  kind: call_expression

ast-grep 0.39+ supports limited ESQuery selectors:

rule:
  kind: call_expression > identifier   # direct child
  kind: call_expression + identifier   # next sibling
  kind: call_expression ~ identifier   # following sibling
  kind: call_expression identifier     # descendant

To find the right kind, parse a known-good file:

sg run -p '$_' --lang ts --debug-query=cst src/foo.ts | head -40

regex

Match node text against a Rust regex. Whole-text match (no partial). Always combine with kind or pattern for performance.

rule:
  all:
    - kind: identifier
    - regex: '^[A-Z][a-z]+$'   # PascalCase

Inline flags work: (?i)apple, (?m)^foo. No look-around, no backreferences.

nthChild

Match by 1-based index among named siblings. Inspired by CSS :nth-child.

rule:
  nthChild: 1                # first sibling

# Functional form
rule:
  nthChild: 2n+1             # odd siblings

# With reverse and ofRule
rule:
  nthChild:
    position: 1
    reverse: true            # last
    ofRule:
      kind: function_declaration

range

Match by character range. Useful for tooling that pinpoints a known location.

rule:
  range:
    start: { line: 0, column: 0 }
    end:   { line: 0, column: 11 }

---

Relational rules — match by relation to other nodes

All four take a sub-rule object plus optional stopBy and (for inside/has) field.

inside — target is inside parent/ancestor matching sub-rule

rule:
  pattern: this.$PROP
  inside:
    kind: class_body
    stopBy: end                # walk up to file root, default: neighbor

has — target has child/descendant matching sub-rule

rule:
  kind: function_declaration
  has:
    kind: throw_statement
    stopBy: end

precedes — target appears before sibling matching sub-rule

rule:
  kind: import_statement
  precedes:
    kind: function_declaration

follows — target appears after sibling matching sub-rule

rule:
  pattern: super($$$)
  follows:
    pattern: $X = $Y

stopBy

field

Specify the semantic role of the target inside its parent (e.g. name, body, value, key).

rule:
  kind: pair
  has:
    field: key
    regex: '^password$'

---

Composite rules — combine sub-rules

rule:
  all:
    - kind: call_expression
    - pattern: $FN($$$ARGS)
    - inside:
        kind: function_declaration
        stopBy: end

rule:
  any:
    - pattern: console.log($X)
    - pattern: console.warn($X)
    - pattern: console.error($X)

rule:
  all:
    - pattern: $E.unwrap()
    - not:
        inside:
          kind: function_item
          has:
            kind: result_type
            stopBy: end

rule:
  matches: is-react-component

Composites apply to a single target. To express "node X has BOTH a number child AND a string child," use two relational rules at the top level, not all inside has. See references/pitfalls.md §10.

---

Implicit all — multiple rule fields

A rule object with multiple fields is treated as an implicit all:

# These two are equivalent
rule:
  pattern: this.$PROP
  inside: { kind: class_body }

rule:
  all:
    - pattern: this.$PROP
    - inside: { kind: class_body }

Use the explicit all array when capture order matters (rare, but possible with downstream transform).

---

constraints — post-match metavariable filtering

After the main rule matches, additional checks on captured single metavariables:

rule:
  pattern: function $NAME($$$P) { $$$B }

constraints:
  NAME:
    regex: '^[a-z][a-zA-Z0-9]*$'   # camelCase only
    not:
      regex: '^_'                   # not starting with _

Constraints only apply to single metavars ($VAR), not multi ($$$VAR).

---

utils — local reusable sub-rules

utils:
  is-literal:
    any:
      - kind: number
      - kind: string
      - kind: 'true'
      - kind: 'false'

rule:
  all:
    - pattern: $X = $Y
    - has:
        matches: is-literal      # references utils.is-literal

For utils accessible across multiple rule files, use utilDirs in sgconfig.yml and put each util in its own YAML file with id and language.

---

transform — manipulate captures before fix

Operations: replace, substring, convert, rewrite.

replace — regex search/replace on a captured string

rule:
  pattern: $OLD_FN($$$A)
constraints:
  OLD_FN:
    regex: '^debug_'
transform:
  NEW_FN:
    replace:
      source: $OLD_FN
      replace: '^debug_'
      by: 'release_'
fix: $NEW_FN($$$A)

substring — character slicing (negative indices supported)

transform:
  INNER:
    substring:
      source: $WRAPPED
      startChar: 1
      endChar: -1

convert — case conversion

transform:
  KEBAB:
    convert:
      source: $CAMEL
      toCase: kebabCase   # camelCase | snakeCase | kebabCase | pascalCase | upperCase | lowerCase | capitalize
      separatedBy: [underscore]   # optional: dash | dot | space | slash | underscore | caseChange

rewrite — apply other rewriter rules (experimental)

rewriters:
  - id: stringify
    rule: { pattern: "'' + $A" }
    fix: "String($A)"

rule:
  pattern: stringify-all($EXPR)
transform:
  REWRITTEN:
    rewrite:
      source: $EXPR
      rewriters: [stringify]
      joinBy: "\n"
fix: $REWRITTEN

Transforms can chain

Later transforms can reference variables produced by earlier ones:

transform:
  KEBABED:
    convert: { source: $X, toCase: kebabCase }
  PREFIXED:
    replace:
      source: $KEBABED
      replace: '^'
      by: 'css-'
fix: $PREFIXED

---

fix — auto-rewrite

String form

fix: logger.log($$$ARGS)

# Empty string deletes the match
fix: ""

FixConfig form (for list-item deletion that needs to expand the range)

When deleting one item from a comma-separated list, you also need to remove the trailing comma. Use expandEnd:

rule:
  kind: pair
  has:
    field: key
    regex: '^password$'

fix:
  template: ''
  expandEnd:
    regex: ','

expandStart and expandEnd accept regex matching characters that should be absorbed into the rewrite range.

---

rewriters — sub-rule library for rewrite transform

Top-level field defining one or more named rewriters:

rewriters:
  - id: nullable-to-optional
    rule: { pattern: $X | null }
    fix: '$X | undefined'

  - id: stringify
    rule: { pattern: "'' + $A" }
    fix: 'String($A)'

Used inside transform via the rewrite operation (see above).

---

labels — custom diagnostic highlighting

rule:
  pattern: $FN($$$ARGS)

labels:
  FN:
    style: primary
    message: "this function shouldn't be called"
  ARGS:
    style: secondary
    message: "with these arguments"

Editor extensions render the diagnostic with these labels. Defaults are usually fine.

---

files and ignores — file selection per-rule

files:
  - 'src/**/*.ts'
  - 'lib/**/*.ts'

ignores:
  - 'src/**/*.test.ts'
  - '**/__generated__/**'

If omitted, the rule runs on every file matching its language. These globs override sgconfig.yml-level globs for this rule only.

Object form (rare):

files:
  - pattern: 'src/**/*.ts'
    case_sensitive: true

---

See also

• references/recipes.md — copy-paste rules by language.
• references/cli.md — sg scan, sg test.
• references/sgconfig.md — project-level configuration.
• Official rule reference: <https://ast-grep.github.io/reference/rule.html>
• Cheat sheets: <https://ast-grep.github.io/cheatsheet/rule.html>, <https://ast-grep.github.io/cheatsheet/yaml.html>