ast-grep

Ast-Grep

Use this skill for ast-grep project setup, rule authoring, rule debugging, and CLI workflows that go beyond a single structural query.

Routing

• Use exec_command for ast-grep queries, project scans, rule tests, debug output, and rewrite previews.
• Use ast-grep scan for project rules and ast-grep test for rule tests.
• Use ast-grep run --pattern=... --rewrite=... --json=compact --color=never for dry-run rewrite previews. Review every replacement before applying changes.
• Use ast-grep run --debug-query when a query matches an unexpected syntax node.
• Use --kind to match node kinds. Ast-grep supports ESQuery-style compound selectors and pseudo-selectors in supported releases.
• Keep this skill read-only unless the user explicitly authorises applying a rewrite.

Quick Start

• In VT Code, prefer vtcode dependencies install ast-grep before suggesting system package managers.
• External install routes such as Homebrew, Cargo, npm, pip, MacPorts, or Nix are fallback options when the user explicitly wants a system-managed install.
• After installation, validate availability with ast-grep --help.
• On Linux, prefer the full ast-grep binary name over sg because sg may already refer to setgroups.
• When running CLI patterns with shell metavariables like $PROP, use single quotes so the shell does not expand them before ast-grep sees the pattern.
• A good first rewrite example is optional chaining, for example rewriting $PROP && $PROP() to $PROP?.().

Command Overview

• ast-grep run: ad-hoc query execution and one-off rewrites.
• ast-grep scan: project rule scanning.
• ast-grep new: scaffold and rule generation.
• ast-grep test: rule-test execution.
• ast-grep lsp: editor integration via language server.

Built-In Languages

• ast-grep ships many built-in languages. Common aliases include bash, c, cc / cpp, cs, css, ex, go / golang, html, java, js / javascript / jsx, json, kt, lua, md / markdown, php, py / python, rb, rs / rust, swift, ts / typescript, tsx, and yml.
• --lang <alias> and YAML language: <alias> use those built-in aliases. File-system scans infer language from built-in extensions unless the project overrides them.
• Pass --lang <alias> to the CLI when extension inference is insufficient.
• Use languageGlobs when the repository needs a different extension mapping than ast-grep’s built-in defaults.