moai-tool-ast-grep

name	moai-tool-ast-grep
description	AST-based structural code search, security scanning, and refactoring using ast-grep (sg CLI) with pattern matching and code transformation across 40+ languages. Use when performing structural code search, AST-based refactoring, codemod operations, security pattern scanning, or syntax-aware code transformations across files. Do NOT use for simple text search (use Grep tool instead) or full codebase exploration (use Explore agent instead).
license	Apache-2.0
compatibility	Designed for Claude Code
allowed-tools	Read Grep Glob Bash(sg:*) Bash(ast-grep:*) mcp__context7__resolve-library-id mcp__context7__get-library-docs
user-invocable	false
metadata	{"version":"1.2.0","category":"tool","modularized":"true","status":"active","updated":"2026-01-11","tags":"ast, refactoring, code-search, lint, structural-search, security, codemod","related-skills":"moai-workflow-testing, moai-foundation-quality, moai-domain-backend, moai-domain-frontend","context":"fork","agent":"Explore"}
triggers	{"keywords":["ast","refactoring","code search","lint","structural search","security","codemod","ast-grep"]}

AST-Grep Integration

Structural code search, lint, and transformation tool using Abstract Syntax Tree analysis.

Quick Reference

What is AST-Grep

AST-Grep (sg) is a fast, polyglot tool for structural code search and transformation. Unlike regex-based search, it understands code syntax and matches patterns based on AST structure.

When to Use

• Searching for code patterns that regex cannot capture such as nested function calls
• Refactoring code across multiple files with semantic awareness
• Security scanning for vulnerability patterns including SQL injection and XSS
• API migration and deprecation handling
• Enforcing code style rules at the syntax level

Core Commands

Pattern search: Execute sg run with pattern option specifying the code pattern to find, lang option for the programming language, and the source directory path.

Security scan with rules: Execute sg scan with config option pointing to your sgconfig.yml file.

Code transformation: Execute sg run with pattern option for the code to find, rewrite option for the replacement, lang option for the language, and source directory path.

Test rules: Execute sg test to validate your rule definitions.

Pattern Syntax Basics

The dollar sign followed by a variable name such as VAR matches any single AST node and acts as a meta-variable for capturing.

The dollar sign followed by three dollar signs and a variable name such as ARGS matches zero or more nodes using variadic capture.

The double dollar sign followed by underscore matches any single node as an anonymous capture when the value is not needed.

Supported Languages

Python, JavaScript, TypeScript, Go, Rust, Java, Kotlin, C, C++, Ruby, Swift, C#, PHP, Scala, Elixir, Lua, HTML, Vue, Svelte, and 30+ more.

---

Implementation Guide

Installation

For macOS, use brew install ast-grep.

For cross-platform via npm, use npm install -g @ast-grep/cli.

For Rust via Cargo, use cargo install ast-grep.

Basic Pattern Matching

Simple Pattern Search

To find all console.log calls, run sg with pattern console.log($MSG) and lang javascript.

To find all Python function definitions, run sg with pattern def $FUNC($$$ARGS): $$$BODY and lang python.

To find React useState hooks, run sg with pattern useState($INIT) and lang tsx.

Explore/Search Performance Optimization

AST-Grep provides significant performance benefits for codebase exploration compared to text-based search:

Why AST-Grep is Faster for Exploration