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.

---

Runtime note (Antigravity)

The upstream version of this skill references mcp__ast_grep_* MCP tools bundled with OmO native. Those tools are NOT registered in Antigravity — do not attempt to call them. In this environment the path is the sg CLI (or ast-grep) resolved via command -v sg; when absent, run install.sh/install.ps1 or the helper's install command, and if installation is not possible, fall back to rg and say the AST-shape search was not performed.

Same pattern language as the CLI: $VAR matches one AST node, $$$VAR matches zero or more, and the pattern is code, not regex. paths accepts a file or directory list; language is required for patterns that are ambiguous across languages.

---

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.