ast-grep

Original：🇺🇸 English

Translated

Effective code search, analysis, and refactoring using ast-grep (sg). Use this skill for precise AST-based code modifications, structural search, and linting.

2installs

Sourceoutlinedriven/odin-codex-plugin

Added on2026-02-08

NPX Install

npx skill4agent add outlinedriven/odin-codex-plugin ast-grep

SKILL.md Content

View Translation Comparison →

ast-grep (sg)

ast-grep is a fast and polyglot tool for code searching, linting, and rewriting based on Abstract Syntax Trees (AST). It excels at structural search and replace where regex fails.

When to use

Structural Search: Finding code based on structure (e.g., "all function calls to
```
foo
```
with 2 arguments") regardless of whitespace.
Refactoring: Renaming variables, changing function signatures, or transforming code patterns safely.
Linting: Creating custom rules to enforce code style or best practices.
Code Analysis: Extracting information from codebases.

Quick Start

CLI Basics

bash

# Search (pattern must be in single quotes)
ast-grep -p '$A + $B' --lang ts

# Rewrite (dry run)
ast-grep -p '$A != null' --rewrite '$A' --lang ts

# Interactive Rewrite
ast-grep -p 'var $A = $B' --rewrite 'const $A = $B' --interactive

Pattern Syntax

Meta-variables:
```
$VAR
```
matches any single node.
Multi-meta-variables:
```
$$$ARGS
```
matches zero or more nodes (list of items).
Wildcard:
```
$_
```
matches any node (non-capturing).
Anonymous:
```
$$
```
matches any list of nodes (non-capturing).

See Pattern Syntax for details.

Core Concepts

Understanding Named vs Unnamed nodes and Matching Strictness is crucial for precise patterns.

Named Nodes:
```
identifier
```
,
```
function_definition
```
(matched by
```
$VAR
```
).
Unnamed Nodes:
```
(
```
,
```
)
```
,
```
;
```
(skipped by default in
```
smart
```
mode).
Strictness: Control matching precision (
```
smart
```
,
```
cst
```
,
```
ast
```
,
```
relaxed
```
,
```
signature
```
).

See Core Concepts for details.

Rule Configuration (YAML)

For complex tasks, use YAML configuration files.

yaml

id: no-console-log
language: TypeScript
rule:
  pattern: console.log($$$ARGS)
  inside:
    kind: function_declaration
    stopBy: end
fix: '' # Remove the log

See Rule Configuration for details.

Advanced Rewriting

ast-grep supports complex transformations (regex replace, case conversion) and rewriters for sub-node transformation.

See Rewriting & Transformations for details.

Project Setup & Testing

For larger projects, organize rules and tests using

sgconfig.yml

Scaffold:
```
ast-grep new project
```
Config:
```
sgconfig.yml
```
defines rule and test directories.
Testing: Define
```
valid
```
and
```
invalid
```
cases to ensure rule accuracy.

See Project Setup & Testing for details.

Utility Rules

Reuse logic with local or global utility rules. Enables recursive matching.

yaml

utils:
  is-literal:
    any: [{kind: string}, {kind: number}]
rule:
  matches: is-literal

See Utility Rules for details.

Configuration Reference

Full reference for YAML fields (

id

severity

files

ignores

) and supported languages.

See Configuration Reference for details.

CLI Reference

Common commands:

scan

run

new

test

lsp

See CLI Reference for details.