Menu
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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Intent-First design craft specialist covering design direction, domain vocabulary, design memory, and post-build critique. Use when establishing design intent or auditing code against design principles.
Design tool integration specialist covering Figma MCP, Pencil renderer, and Pencil-to-code export. Use when fetching design context from Figma, rendering Pencil designs, or exporting to React/Tailwind code.
Documentation generation patterns for technical specs, API docs, user guides, and knowledge bases using real tools like Sphinx, MkDocs, TypeDoc, and Nextra. Use when creating docs from code, building doc sites, or automating documentation workflows.
Backend development specialist covering API design, database integration, microservices architecture, and modern backend patterns. Use when designing APIs, implementing server logic, authentication, or authorization.
Brand-aligned visual design system specialist for web projects. Enforces hero-first layout chaining, WCAG 2.1 AA accessibility, Lighthouse >= 80, and design token extraction from brand identity files. Covers color palettes, typography, spacing, and component specifications.
Brand-aligned copywriting specialist for marketing and product text. Enforces brand voice, anti-AI-slop rules, concrete numbers, and JSON section structure for downstream agent consumption. Covers hero, features, social_proof, cta, and footer sections with A/B variant output.
| 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"]} |
Structural code search, lint, and transformation tool using Abstract Syntax Tree analysis.
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.
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.
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.
Python, JavaScript, TypeScript, Go, Rust, Java, Kotlin, C, C++, Ruby, Swift, C#, PHP, Scala, Elixir, Lua, HTML, Vue, Svelte, and 30+ more.
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.
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.
AST-Grep provides significant performance benefits for codebase exploration compared to text-based search:
Why AST-Grep is Faster for Exploration
Common Exploration Patterns
Find all function calls matching a pattern:
sg -p 'authenticate($$$)' --lang python -r src/
Find all classes inheriting from a base class:
sg -p 'class $A extends BaseService' --lang python -r src/
Find specific import patterns:
sg -p 'import fastapi' --lang python -r src/
Find React hooks usage:
sg -p 'useState($$)' --lang tsx -r src/
Find async function declarations:
sg -p 'async def $NAME($$$ARGS):' --lang python -r src/
Performance Comparison
grep -r "class.*Service" src/ - scans all files textually (~10s for large codebase)sg -p 'class $X extends Service' --lang python -r src/ - structural match (~2s)Integration with Explore Agent When using the Explore agent, AST-Grep is automatically prioritized for:
Meta-variables capture matching AST nodes in patterns.
Single node capture uses $NAME syntax. For example, pattern const $NAME = require($PATH) captures the variable name and path.
Variadic capture uses $$$ARGS syntax. For example, pattern function $NAME($$$ARGS) captures function name and all arguments.
Anonymous single capture uses $$_ syntax when you need to match but not reference the value.
To rename a function, run sg with pattern oldFunc($ARGS), rewrite newFunc($ARGS), and lang python.
To update an API call, run sg with pattern axios.get($URL), rewrite fetch($URL), and lang typescript.
Create a YAML rule file with the following structure. Set the id field to a unique rule identifier such as convert-var-to-const. Set language to the target language such as javascript. Under the rule section, specify the pattern to match such as var $NAME = $VALUE. Set the fix field to the replacement pattern such as const $NAME = $VALUE. Add a message describing the issue and set severity to warning or error.
Run sg scan with the rule option pointing to your rule file and the source directory.
Create an sgconfig.yml file with the following sections. The ruleDirs section lists directories containing rule files such as ./rules/security and ./rules/quality. The testConfigs section specifies test file patterns. The languageGlobs section maps languages to file patterns, mapping python to .py files, typescript to .ts and .tsx files, and javascript to .js and .jsx files.
Create a security rule file for SQL injection detection. Set the id to sql-injection-risk. Set language to python and severity to error. Write a descriptive message about the vulnerability. Under the rule section, use the any operator to match multiple patterns including cursor.execute with percent formatting, cursor.execute with format method, and cursor.execute with f-string interpolation. Set the fix to show the parameterized query alternative.
Create a rule that searches for console.log calls only inside function declarations. Set the pattern to console.log($$$ARGS) and add an inside constraint with pattern function $NAME($$$PARAMS).
Create a rule to find async functions without await. Set the pattern to async function $NAME($$$PARAMS) with a not constraint containing a has rule with pattern await $EXPR. Add message indicating async function without await.
Create a rule to detect missing error handling. Set the pattern to match error assignment $ERR := $CALL and add a not constraint with follows rule checking for if $ERR != nil error handling block.
Create complex rules using the all operator to combine multiple conditions. For example, combine pattern useState($INIT) with inside constraint for function component and not precedes constraint for useEffect call.
For comprehensive documentation including complex multi-file transformations, custom language configuration, CI/CD integration patterns, and performance optimization tips, see the following module files.
Pattern syntax reference is available in modules/pattern-syntax.md.
Security scanning rule templates are documented in modules/security-rules.md.
Common refactoring patterns are covered in modules/refactoring-patterns.md.
Language-specific patterns are detailed in modules/language-specific.md.
For latest AST-Grep documentation, follow this two-step process.
Step 1: Use mcp__context7__resolve-library-id with query ast-grep to resolve the library identifier.
Step 2: Use mcp__context7__get-library-docs with the resolved library ID to fetch current documentation.
AST-Grep is integrated into MoAI-ADK through the Tool Registry as AST_ANALYZER type in internal/hook/registry.go, PostToolUse Hook for automatic security scanning after Write/Edit operations, and Permissions with Bash(sg:) and Bash(ast-grep:) auto-allowed.
To scan with MoAI-ADK rules, execute sg scan with config pointing to .claude/skills/moai-tool-ast-grep/rules/sgconfig.yml.
To scan a specific directory, execute sg scan with config sgconfig.yml and the src/ directory.
For JSON output suitable for CI/CD, execute sg scan with config and json flag, redirecting to results.json.
For additional information, consult the AST-Grep Official Documentation at ast-grep.github.io, the AST-Grep GitHub Repository at github.com/ast-grep/ast-grep, the Pattern Playground at ast-grep.github.io/playground.html, and the Rule Configuration Reference at ast-grep.github.io/reference/yaml.html.
| Rationalization | Reality |
|---|---|
| "Regex search is good enough for finding code patterns" | Regex matches text, not structure. Searching for function matches comments, strings, and variable names. AST matching is structural. |
| "I will review the codemod output manually, dry-run is unnecessary" | Codemods at scale produce hundreds of changes. Manual review without dry-run misses edge cases in obscure files. |
| "This rule is too strict, I will disable it globally" | Global disable hides all violations, including legitimate ones. Disable per-file with inline comments and justification. |
| "ast-grep is overkill for a small refactor" | Small refactors across many files are exactly where ast-grep prevents missed occurrences. Manual find-replace misses variants. |
| "The pattern works in the playground, it will work on the codebase" | Playground uses a single file context. Codebase patterns encounter language variants, file encodings, and edge cases. Always dry-run. |
Rule of 500: For changes affecting more than 500 lines, automated structural search is more reliable than manual inspection. ast-grep provides the structural guarantee that regex cannot.