| 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 for structural search or codemod operations.
|
| 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
