Claude Cursor opencode Skill

ast-grep

Use ast-grep (sg) for AST-aware code search and rewrite across 25 languages. Trigger for structural code matching or deterministic codemods: find every function/call/class/import shaped like X, rewrite console.log to logger.info, strip `as any`, migrate require() to import, find

LLM Mart · 0 points · 16 views 0 listing impressions 0 install-command copies
Download code-yeongyu-oh-my-openagent-packages_shared-skills_skills_ast-grep-05dcba6.zip · 51 KB
This skill couldn't be refreshed from GitHub on the last check — you're seeing the last imported snapshot.

Install

skills CLI npx skills add https://github.com/code-yeongyu/oh-my-openagent/tree/dev/packages/shared-skills/skills/ast-grep
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install code-yeongyu-oh-my-openagent@llmmart
Git git clone https://github.com/code-yeongyu/oh-my-openagent.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole code-yeongyu/oh-my-openagent collection as a plugin from our marketplace. Git is the plain clone.

README

ast-grep-skill

LLM-neutral skill for AST-aware search and rewrite across 25 languages. Wraps the ast-grep (sg) CLI with offline pattern validation, the two-pass write trick, binary auto-resolution, and a per-OS installer.

Same shape as web-fetch and web-search, packaged as a standalone skill that any Bash-capable agent (Claude Code, OpenCode, pi, hermes, openclaw) can load.

Install

git clone https://github.com/code-yeongyu/ast-grep-skill ~/.agents/skills/ast-grep
bash ~/.agents/skills/ast-grep/install.sh        # installs the ast-grep binary

That is it. The wrapper script is single-file Python 3 stdlib; no pip install needed. The installer tries brew → npm → cargo → pip → nix → mise → GitHub release in priority order, picks the first that works, and falls back to a cached binary at <skill>/bin/sg.

Symlink for active development

ln -s /path/to/your/clone ~/.agents/skills/ast-grep

Other agents

  • Claude Code / OpenCode: drop the directory under ~/.agents/skills/ (or ~/.config/opencode/skills/) and the skill auto-registers via the name + description in SKILL.md frontmatter.
  • pi (~/.senpi/agent): not a pi extension — this is a skill. Pi consumes skills via ~/.agents/skills/ symlinks; the actual pi-ast-grep extension is at https://github.com/code-yeongyu/pi-extensions.
  • Direct CLI use: python3 ~/.agents/skills/ast-grep/scripts/ast_grep_helper.py <subcommand>.

Usage

# Search by AST pattern (the helper validates patterns offline first)
python3 scripts/ast_grep_helper.py search 'console.log($MSG)' --lang ts src/

# Rewrite (dry-run preview by default)
python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/

# Apply the rewrite (two-pass: preview JSON + then --update-all)
python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/ --apply

# Run YAML lint rules from sgconfig.yml
python3 scripts/ast_grep_helper.py scan src/

# Validate a pattern OFFLINE (no sg call, no filesystem)
python3 scripts/ast_grep_helper.py validate '\w+' --lang ts
# → exit 2: regex \w not supported. Use $VAR for identifiers.

# Doctor: check ast-grep binary availability
python3 scripts/ast_grep_helper.py doctor

# List 25 supported languages
python3 scripts/ast_grep_helper.py langs

# Install / re-install the ast-grep binary
python3 scripts/ast_grep_helper.py install

See SKILL.md for full agent-facing usage and the references/ directory for deep dives.

Project layout

ast-grep-skill/
├── SKILL.md                       agent-facing skill (loaded by Claude Code, OpenCode, pi, etc.)
├── README.md                      this file
├── LICENSE                        MIT
├── install.sh                     POSIX installer (macOS / Linux / WSL / Git Bash)
├── install.ps1                    Windows PowerShell installer
├── scripts/
│   └── ast_grep_helper.py         single-file Python 3 stdlib wrapper
├── references/
│   ├── install.md                 per-OS install methods + manual fallback
│   ├── patterns.md                meta-variables ($VAR, $$$) and pattern syntax
│   ├── pitfalls.md                regex anti-patterns + language-specific traps
│   ├── recipes.md                 copy-paste patterns by language (TS/JS/Py/Go/Rust/...)
│   ├── cli.md                     sg run / scan / test / new / lsp reference
│   ├── yaml-rules.md              YAML rule schema (atomic / relational / composite / transform / fix)
│   └── sgconfig.md                project configuration (ruleDirs, testConfigs, utilDirs)
├── tests/
│   ├── smoke.sh                   POSIX self-test
│   └── smoke.ps1                  PowerShell self-test (Windows CI)
└── .github/workflows/ci.yml       matrix CI: macos / ubuntu / windows × py 3.9-3.13

What it does

  1. Wraps sg with a single Python 3 stdlib script that works the same on macOS, Linux, Windows, WSL, Git Bash.
  2. Validates patterns offline before calling sg — catches the regex-misuse class of mistakes (\w, .*, |, [a-z]) plus language-specific traps (Python trailing colons, JS/Go/Rust missing function bodies).
  3. Resolves the binary through 6 candidate paths: cached → PATH (with Linux setgroups collision detection) → Homebrew. Falls through to a clear install hint with copy-paste commands.
  4. Runs the two-pass write trick when applying rewrites — sg run silently ignores --update-all when --json is set, so replace --apply runs two invocations: pass 1 collects JSON matches, pass 2 mutates files.
  5. Ships per-OS installers that try every reasonable package manager and fall back to a GitHub release tarball.
  6. Documents the failure modes the model will hit (regex misuse, incomplete patterns, --update-all + --json trap, scope/type questions ast-grep can't answer) in references/pitfalls.md.

What it does NOT do

  • No type inference, scope analysis, or data flow. ast-grep is a structural matcher; for type-aware questions use TypeScript LSP, Pyright, Semgrep with type inference, or CodeQL.
  • No multi-repo federation. Run the helper once per repo.
  • No automatic sgconfig.yml discovery — it does what sg scan does (walk up from cwd looking for one).
  • No JS/Python rewriter authoring environment — for that, write YAML rules and use sg test for snapshot testing (see references/yaml-rules.md).

Limits

  • 5-minute timeout per sg invocation (configurable in the helper).
  • ast-grep itself supports 25 languages out-of-the-box. For anything else, use customLanguages in sgconfig.yml.
  • Pattern hint detection is heuristic; pass --force to skip validation when you know the pattern is correct.

Requirements

  • Python ≥ 3.9 (stdlib only — no pip install).
  • ast-grep binary, installed via install.sh / install.ps1 or one of:
    • brew install ast-grep (macOS / linuxbrew)
    • npm install -g @ast-grep/cli (any OS with Node)
    • cargo install ast-grep --locked (any OS with Rust)
    • pip install ast-grep-cli (any OS with Python)
    • scoop install main/ast-grep (Windows)

For older systems and Windows-specific setup, see references/install.md.

Testing

bash tests/smoke.sh        # POSIX (macOS / Linux / WSL / Git Bash)
pwsh tests/smoke.ps1       # Windows (PowerShell 5.1+ or 7+)

CI runs the matrix on every push: {macos-latest, ubuntu-latest, ubuntu-22.04, windows-latest} × {Python 3.9, 3.10, 3.11, 3.12, 3.13} plus a syntax-floor check on Python 3.9 and 3.10.

License

MIT.

Acknowledgments

  • omo (oh-my-opencode) — src/tools/ast-grep/ is the original tool implementation; this skill is a port of its pattern-hint detection and two-pass-write strategy.
  • pi-extensions/pi-ast-grep — sibling Node port; the helper's binary-resolution cascade is modelled on it.
  • ast-grep — the CLI. All structural matching power comes from it.
  • Anthropic skills — the SKILL.md + references/ packaging convention.

Skill manifest

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.


OmO native: the ast-grep MCP tools (fastest path, no CLI needed)

OmO native also registers a bundled ast-grep MCP server. Its three tools are deferred: they are absent from the resident tool list and activate automatically the first time you call them by name — no tool_search round trip needed.

  • mcp__ast_grep_search({ pattern, language, paths }) — AST-shape search, the MCP equivalent of sg run -p. Prefer this over shelling out to sg for one-off lookups: no install, no PATH issues.
  • mcp__ast_grep_rewrite({ pattern, rewrite, language, paths, apply }) — preview matches (apply: false, the default) or apply the rewrite (apply: true). Same two-pass discipline as sg run -r: preview first, then apply.
  • mcp__ast_grep_scan({ paths }) — run project YAML rules (sgconfig.yml, rules/), the MCP equivalent of sg scan.

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.


Three things the agent must internalize

1. ast-grep is NOT regex

The wildcards are $VAR (one AST node) and $$$ (zero or more nodes). Regex syntax fails silently:

You wrote What ast-grep saw What you wanted
foo\|bar bitwise-or of foo and bar run two separate searches
.*foo not parseable $$$ foo (if $$$ is a list of nodes) or use rg
\w+ not parseable $VAR to capture any identifier
[a-z] character class, not parseable switch to rg

The full anti-pattern table is in references/pitfalls.md §1. The helper's validate subcommand catches these mechanically — call it before debugging "no matches" by hand.

2. Patterns must be valid code

The pattern itself must parse. def $FN($$$): fails because the trailing : makes it incomplete; use def $FN($$$). function $NAME without params/body fails; use function $NAME($$$) { $$$ }. Full table per language in references/pitfalls.md §2.

3. --update-all and --json are mutually exclusive (silently)

This is the single biggest gotcha when scripting. sg run -p P -r R --json --update-all returns the JSON but does not mutate files. To both preview AND apply, run two passes:

sg run -p P -r R --json=compact .   # pass 1: see what would change
sg run -p P -r R --update-all .     # pass 2: actually apply

The helper does this automatically when you call replace --apply. Read references/pitfalls.md §9.


The helper script — scripts/ast_grep_helper.py

A single-file Python 3 stdlib wrapper. Same on every OS. The agent's default entry point.

search — find all matches of a pattern

python3 scripts/ast_grep_helper.py search 'console.log($MSG)' --lang ts src/

Validates the pattern offline first. If the pattern looks like regex (\w, .*, |, etc.) the helper exits with a hint and never calls sg — saves a round-trip. Pass --force to skip validation.

Flags:

  • --lang ts (or any of the 25 languages; aliases like js, py, rs, kt accepted)
  • --globs '!**/*.test.ts' (repeatable; prefix ! to exclude)
  • -C 3 (context lines)
  • --json-out (raw JSON instead of human format)

replace — rewrite by pattern, dry-run by default

# Dry-run preview (default — no files mutated)
python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/

# Actually apply
python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/ --apply

The helper:

  1. Validates both pattern and rewrite for hint-detectable mistakes.
  2. Runs pass 1 with --json=compact to collect matches and show a preview.
  3. If --apply is set, runs pass 2 with --update-all to mutate files.

scan — run YAML rules

# Discover sgconfig.yml from cwd and run all rules
python3 scripts/ast_grep_helper.py scan src/

# Run a single rule file
python3 scripts/ast_grep_helper.py scan -r rules/no-console.yml src/

# Apply auto-fixes
python3 scripts/ast_grep_helper.py scan -U src/

# CI-friendly GitHub annotations
python3 scripts/ast_grep_helper.py scan --report-style short src/

validate — offline pattern check (no sg call)

Useful for CI lints, pre-commit hooks, and quick sanity checks:

python3 scripts/ast_grep_helper.py validate '\w+' --lang ts
# → exit 2: regex \w not supported. Use $VAR for identifiers.

python3 scripts/ast_grep_helper.py validate 'console.log($MSG)' --lang ts
# → exit 0: pattern looks plausible for ast-grep.

langs / doctor / install

python3 scripts/ast_grep_helper.py langs       # list 25 supported languages and aliases
python3 scripts/ast_grep_helper.py doctor      # check ast-grep binary availability
python3 scripts/ast_grep_helper.py install     # delegate to install.sh / install.ps1

new and test subcommands proxy directly to sg new and sg test.


Direct sg use (when the helper isn't enough)

The helper is opinionated. For full control, drop to sg. The skill ships a CLI cheat sheet in references/cli.md. The minimal idioms:

# Search
sg run -p 'console.log($MSG)' --lang ts src/

# Search with JSON for scripting
sg run -p 'console.log($MSG)' --lang ts --json=compact src/ | jq '.[] | .file'

# Rewrite, dry-run
sg run -p 'console.log($MSG)' -r 'logger.info($MSG)' --lang ts --json=compact src/

# Rewrite, apply
sg run -p 'console.log($MSG)' -r 'logger.info($MSG)' --lang ts --update-all src/

# Pattern from stdin (great for ad-hoc experiments)
echo 'console.log("hi")' | sg run -p 'console.log($MSG)' --lang js --stdin

# Debug a pattern that returns 0 matches
sg run -p '<your pattern>' --lang <lang> --debug-query=ast --stdin <<< '<sample-code>'

# Run YAML rules
sg scan src/

# Inline YAML rule (one-off)
sg scan --inline-rules '
id: no-todo
language: TypeScript
severity: warning
rule: { pattern: TODO }' src/

When using sg directly in a shell, always single-quote patterns so $VAR is not expanded by the shell.


Decision tree — what to use, when

USER asks for "find/rewrite/codemod"
│
├─ structural pattern (function shape, call, class, import, control flow)
│  └→ ast-grep (this skill)
│
├─ text pattern (regex, alternation, character classes, file names)
│  └→ rg / grep
│
├─ semantic question (what variable does this refer to? does this throw?)
│  └→ LSP tools, TypeScript compiler, Pyright, Semgrep with type inference
│
└─ multiple repos / federated search
   └→ a search engine + then ast-grep / rg / LSP per-repo

If the user says "find all" or "every", default to ast-grep when the target is shaped (function, class, call, import, statement). Default to rg when the target is text (string content, comment, license header, file name, identifier substring).


Always run dry-run first when rewriting

A bad pattern silently rewrites the wrong thing. The helper's replace defaults to dry-run for this reason. The flow is:

  1. Search to confirm matches: helper search '<pattern>' --lang X .
  2. Dry-run rewrite: helper replace '<pattern>' '<rewrite>' --lang X . (no --apply)
  3. Inspect the dry-run summary: number of matches, files affected, the per-location preview.
  4. If wrong: refine pattern, go back to step 1.
  5. If right: helper replace '<pattern>' '<rewrite>' --lang X . --apply.

Never apply a rewrite that you have not first dry-run.


When sg returns 0 matches but you know the code is there

In priority order:

  1. Run helper validate '<pattern>' --lang <lang> — catches regex misuse, missing function bodies, Python trailing colons.
  2. Check --lang — sg infers from extension; if you pass a .tsx file with --lang ts (not tsx), JSX won't parse.
  3. Inspect the parsed pattern: sg run -p '<pattern>' --lang <lang> --debug-query=ast --stdin <<< '<sample>'. If it shows ERROR nodes, the pattern is malformed.
  4. Check the AST of the target file: sg run -p '$_' --lang <lang> --debug-query=cst path/to/file | head -40 — find the kind you're trying to match.
  5. Try the playground: https://ast-grep.github.io/playground.html — paste code + pattern, see what's happening.

Do not blindly retry with variations. Each failure has a reason; surface it.


When to use YAML rules vs inline -p patterns

Use inline -p when:

  • One-off ad-hoc query.
  • The pattern is simple (no constraints, no fix template).
  • You're exploring.

Use YAML rules (file under rules/, run via sg scan) when:

  • The pattern is reused (lint rule, codemod that runs in CI).
  • You need constraints, transform, complex inside/has, or composite logic.
  • You want auto-fix (fix: field).
  • You want to test the rule (snapshot tests via sg test).

The full YAML rule schema is in references/yaml-rules.md. Project setup (sgconfig.yml, ruleDirs, utilDirs) is in references/sgconfig.md.


Output discipline

  • sg run --json=compact produces an array of match objects: { file, range: {start, end}, text, replacement?, lines, language, ... }. Pipe through jq for further processing.
  • Without --json, sg produces human-readable colored output suitable for terminals.
  • The helper's default output is human-readable (file:line:column + match preview). Pass --json-out for raw JSON.
  • The helper's replace always summarizes: number of matches, number of files, per-location preview.

When summarizing for the user, always include the count of files affected, not just the count of matches. Users care about blast radius.


Required reading (in order of priority)

  1. references/patterns.md — meta-variables, naming rules, strictness levels. Read when you're unsure why a pattern doesn't match.
  2. references/pitfalls.md — the failure-mode field guide. Read when 0 matches surprises you.
  3. references/recipes.md — copy-paste patterns by language. Read first when you start a new task.
  4. references/cli.md — sg run, sg scan, sg test, sg new, sg lsp. Read when the helper isn't enough.
  5. references/yaml-rules.md — YAML rule schema. Read when you outgrow inline patterns.
  6. references/sgconfig.md — project-level configuration. Read when you set up sg scan for a real project.
  7. references/install.md — per-OS install methods. Read only if install.sh / install.ps1 fail.

Invariants (do not break)

  • Validate before searching. When emitting a pattern programmatically, call helper validate first. It catches the regex-misuse class of mistakes that account for ~70% of "0 matches" debug sessions.
  • Dry-run before applying. Never run sg run -r ... --update-all without first inspecting the matches. The helper's replace enforces this by default.
  • Two-pass writes. When using sg directly to both preview and apply, run two invocations — --json ignores --update-all.
  • Single-quote patterns in shell. '$VAR' not "$VAR". The shell expands $VAR to the empty string in double quotes, breaking the pattern.
  • Pattern is code, not regex. When the pattern would need |, .*, \w, or [a-z], switch to rg instead. Don't try to force ast-grep into a regex shape.
  • --lang is required for stdin. When piping with --stdin, set --lang explicitly; sg cannot infer from extension.
  • Linux: prefer ast-grep over sg because sg collides with setgroups. The helper handles this; if you call sg directly, alias it: alias sg=ast-grep.
Files (oh-my-openagent)
  • references
    • cli.md 7.1 KB
      Loading…
    • install.md 5.5 KB
      Loading…
    • patterns.md 5.4 KB
      Loading…
    • pitfalls.md 8.7 KB
      Loading…
    • recipes.md 7.7 KB
      Loading…
    • sgconfig.md 6.3 KB
      Loading…
    • yaml-rules.md 11.1 KB
      Loading…
  • scripts
    • ast_grep_helper.py 26.3 KB
      Loading…
  • tests
    • smoke.ps1 5.6 KB · in bundle
    • smoke.sh 7.6 KB
      Loading…
  • .gitignore 343 B · in bundle
  • AGENTS.md 3.1 KB
    Loading…
  • install.ps1 7 KB · in bundle
  • install.sh 7.4 KB
    Loading…
  • LICENSE 1 KB · in bundle
  • README.md 7.5 KB
    # ast-grep-skill
    
    LLM-neutral skill for **AST-aware search and rewrite** across 25 languages. Wraps the [`ast-grep`](https://ast-grep.github.io/) (`sg`) CLI with offline pattern validation, the two-pass write trick, binary auto-resolution, and a per-OS installer.
    
    Same shape as [`web-fetch`](https://github.com/code-yeongyu/web-fetch) and [`web-search`](https://github.com/code-yeongyu/web-search), packaged as a standalone skill that any Bash-capable agent (Claude Code, OpenCode, pi, hermes, openclaw) can load.
    
    ## Install
    
    ```bash
    git clone https://github.com/code-yeongyu/ast-grep-skill ~/.agents/skills/ast-grep
    bash ~/.agents/skills/ast-grep/install.sh        # installs the ast-grep binary
    ```
    
    That is it. The wrapper script is single-file Python 3 stdlib; no `pip install` needed. The installer tries `brew` → `npm` → `cargo` → `pip` → `nix` → `mise` → GitHub release in priority order, picks the first that works, and falls back to a cached binary at `<skill>/bin/sg`.
    
    ### Symlink for active development
    
    ```bash
    ln -s /path/to/your/clone ~/.agents/skills/ast-grep
    ```
    
    ### Other agents
    
    - **Claude Code / OpenCode**: drop the directory under `~/.agents/skills/` (or `~/.config/opencode/skills/`) and the skill auto-registers via the `name` + `description` in `SKILL.md` frontmatter.
    - **pi (`~/.senpi/agent`)**: not a `pi` extension — this is a skill. Pi consumes skills via `~/.agents/skills/` symlinks; the actual `pi-ast-grep` extension is at <https://github.com/code-yeongyu/pi-extensions>.
    - **Direct CLI use**: `python3 ~/.agents/skills/ast-grep/scripts/ast_grep_helper.py <subcommand>`.
    
    ## Usage
    
    ```bash
    # Search by AST pattern (the helper validates patterns offline first)
    python3 scripts/ast_grep_helper.py search 'console.log($MSG)' --lang ts src/
    
    # Rewrite (dry-run preview by default)
    python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/
    
    # Apply the rewrite (two-pass: preview JSON + then --update-all)
    python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/ --apply
    
    # Run YAML lint rules from sgconfig.yml
    python3 scripts/ast_grep_helper.py scan src/
    
    # Validate a pattern OFFLINE (no sg call, no filesystem)
    python3 scripts/ast_grep_helper.py validate '\w+' --lang ts
    # → exit 2: regex \w not supported. Use $VAR for identifiers.
    
    # Doctor: check ast-grep binary availability
    python3 scripts/ast_grep_helper.py doctor
    
    # List 25 supported languages
    python3 scripts/ast_grep_helper.py langs
    
    # Install / re-install the ast-grep binary
    python3 scripts/ast_grep_helper.py install
    ```
    
    See [SKILL.md](./SKILL.md) for full agent-facing usage and the [`references/`](./references/) directory for deep dives.
    
    ## Project layout
    
    ```
    ast-grep-skill/
    ├── SKILL.md                       agent-facing skill (loaded by Claude Code, OpenCode, pi, etc.)
    ├── README.md                      this file
    ├── LICENSE                        MIT
    ├── install.sh                     POSIX installer (macOS / Linux / WSL / Git Bash)
    ├── install.ps1                    Windows PowerShell installer
    ├── scripts/
    │   └── ast_grep_helper.py         single-file Python 3 stdlib wrapper
    ├── references/
    │   ├── install.md                 per-OS install methods + manual fallback
    │   ├── patterns.md                meta-variables ($VAR, $$$) and pattern syntax
    │   ├── pitfalls.md                regex anti-patterns + language-specific traps
    │   ├── recipes.md                 copy-paste patterns by language (TS/JS/Py/Go/Rust/...)
    │   ├── cli.md                     sg run / scan / test / new / lsp reference
    │   ├── yaml-rules.md              YAML rule schema (atomic / relational / composite / transform / fix)
    │   └── sgconfig.md                project configuration (ruleDirs, testConfigs, utilDirs)
    ├── tests/
    │   ├── smoke.sh                   POSIX self-test
    │   └── smoke.ps1                  PowerShell self-test (Windows CI)
    └── .github/workflows/ci.yml       matrix CI: macos / ubuntu / windows × py 3.9-3.13
    ```
    
    ## What it does
    
    1. **Wraps `sg`** with a single Python 3 stdlib script that works the same on macOS, Linux, Windows, WSL, Git Bash.
    2. **Validates patterns offline** before calling `sg` — catches the regex-misuse class of mistakes (`\w`, `.*`, `|`, `[a-z]`) plus language-specific traps (Python trailing colons, JS/Go/Rust missing function bodies).
    3. **Resolves the binary** through 6 candidate paths: cached → PATH (with Linux `setgroups` collision detection) → Homebrew. Falls through to a clear install hint with copy-paste commands.
    4. **Runs the two-pass write trick** when applying rewrites — `sg run` silently ignores `--update-all` when `--json` is set, so `replace --apply` runs two invocations: pass 1 collects JSON matches, pass 2 mutates files.
    5. **Ships per-OS installers** that try every reasonable package manager and fall back to a GitHub release tarball.
    6. **Documents the failure modes** the model will hit (regex misuse, incomplete patterns, `--update-all` + `--json` trap, scope/type questions ast-grep can't answer) in `references/pitfalls.md`.
    
    ## What it does NOT do
    
    - No type inference, scope analysis, or data flow. ast-grep is a structural matcher; for type-aware questions use TypeScript LSP, Pyright, Semgrep with type inference, or CodeQL.
    - No multi-repo federation. Run the helper once per repo.
    - No automatic `sgconfig.yml` discovery — it does what `sg scan` does (walk up from cwd looking for one).
    - No JS/Python rewriter authoring environment — for that, write YAML rules and use `sg test` for snapshot testing (see [`references/yaml-rules.md`](./references/yaml-rules.md)).
    
    ## Limits
    
    - 5-minute timeout per `sg` invocation (configurable in the helper).
    - ast-grep itself supports 25 languages out-of-the-box. For anything else, use [`customLanguages`](./references/sgconfig.md#customlanguages-experimental) in `sgconfig.yml`.
    - Pattern hint detection is heuristic; pass `--force` to skip validation when you know the pattern is correct.
    
    ## Requirements
    
    - Python ≥ 3.9 (stdlib only — no pip install).
    - `ast-grep` binary, installed via `install.sh` / `install.ps1` or one of:
      - `brew install ast-grep` (macOS / linuxbrew)
      - `npm install -g @ast-grep/cli` (any OS with Node)
      - `cargo install ast-grep --locked` (any OS with Rust)
      - `pip install ast-grep-cli` (any OS with Python)
      - `scoop install main/ast-grep` (Windows)
    
    For older systems and Windows-specific setup, see [`references/install.md`](./references/install.md).
    
    ## Testing
    
    ```bash
    bash tests/smoke.sh        # POSIX (macOS / Linux / WSL / Git Bash)
    pwsh tests/smoke.ps1       # Windows (PowerShell 5.1+ or 7+)
    ```
    
    CI runs the matrix on every push: `{macos-latest, ubuntu-latest, ubuntu-22.04, windows-latest}` × `{Python 3.9, 3.10, 3.11, 3.12, 3.13}` plus a syntax-floor check on Python 3.9 and 3.10.
    
    ## License
    
    [MIT](./LICENSE).
    
    ## Acknowledgments
    
    - [`omo` (oh-my-opencode)](https://github.com/code-yeongyu/oh-my-opencode) — `src/tools/ast-grep/` is the original tool implementation; this skill is a port of its pattern-hint detection and two-pass-write strategy.
    - [`pi-extensions/pi-ast-grep`](https://github.com/code-yeongyu/pi-extensions) — sibling Node port; the helper's binary-resolution cascade is modelled on it.
    - [ast-grep](https://github.com/ast-grep/ast-grep) — the CLI. All structural matching power comes from it.
    - [Anthropic skills](https://docs.anthropic.com/en/docs/claude-code/skills) — the `SKILL.md` + `references/` packaging convention.
    
  • SKILL.md 13.1 KB
    ---
    name: ast-grep
    description: "Searches and rewrites code by AST shape across 25 languages. Use when the target is a syntax pattern (every call/class/import shaped like X, a codemod, a YAML rule) rather than literal text; for plain strings, comments, or filenames, use rg."
    ---
    
    # 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.
    
    ---
    
    ## OmO native: the ast-grep MCP tools (fastest path, no CLI needed)
    
    OmO native also registers a bundled ast-grep MCP server. Its three tools are **deferred**: they are absent from the resident tool list and activate automatically the first time you call them by name — no `tool_search` round trip needed.
    
    - `mcp__ast_grep_search({ pattern, language, paths })` — AST-shape search, the MCP equivalent of `sg run -p`. Prefer this over shelling out to `sg` for one-off lookups: no install, no PATH issues.
    - `mcp__ast_grep_rewrite({ pattern, rewrite, language, paths, apply })` — preview matches (`apply: false`, the default) or apply the rewrite (`apply: true`). Same two-pass discipline as `sg run -r`: preview first, then apply.
    - `mcp__ast_grep_scan({ paths })` — run project YAML rules (`sgconfig.yml`, `rules/`), the MCP equivalent of `sg scan`.
    
    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.
    
    ---
    
    ## Three things the agent must internalize
    
    ### 1. ast-grep is NOT regex
    
    The wildcards are `$VAR` (one AST node) and `$$$` (zero or more nodes). Regex syntax fails silently:
    
    | You wrote | What ast-grep saw | What you wanted |
    |---|---|---|
    | `foo\|bar` | bitwise-or of `foo` and `bar` | run two separate searches |
    | `.*foo` | not parseable | `$$$ foo` (if `$$$` is a list of nodes) or use `rg` |
    | `\w+` | not parseable | `$VAR` to capture any identifier |
    | `[a-z]` | character class, not parseable | switch to `rg` |
    
    The full anti-pattern table is in `references/pitfalls.md` §1. The helper's `validate` subcommand catches these mechanically — call it before debugging "no matches" by hand.
    
    ### 2. Patterns must be valid code
    
    The pattern itself must parse. `def $FN($$$):` fails because the trailing `:` makes it incomplete; use `def $FN($$$)`. `function $NAME` without params/body fails; use `function $NAME($$$) { $$$ }`. Full table per language in `references/pitfalls.md` §2.
    
    ### 3. `--update-all` and `--json` are mutually exclusive (silently)
    
    This is the single biggest gotcha when scripting. `sg run -p P -r R --json --update-all` returns the JSON but **does not mutate files**. To both preview AND apply, run **two passes**:
    
    ```bash
    sg run -p P -r R --json=compact .   # pass 1: see what would change
    sg run -p P -r R --update-all .     # pass 2: actually apply
    ```
    
    The helper does this automatically when you call `replace --apply`. Read `references/pitfalls.md` §9.
    
    ---
    
    ## The helper script — `scripts/ast_grep_helper.py`
    
    A single-file Python 3 stdlib wrapper. Same on every OS. The agent's default entry point.
    
    ### `search` — find all matches of a pattern
    
    ```bash
    python3 scripts/ast_grep_helper.py search 'console.log($MSG)' --lang ts src/
    ```
    
    Validates the pattern offline first. If the pattern looks like regex (`\w`, `.*`, `|`, etc.) the helper exits with a hint and never calls `sg` — saves a round-trip. Pass `--force` to skip validation.
    
    Flags:
    - `--lang ts` (or any of the 25 languages; aliases like `js`, `py`, `rs`, `kt` accepted)
    - `--globs '!**/*.test.ts'` (repeatable; prefix `!` to exclude)
    - `-C 3` (context lines)
    - `--json-out` (raw JSON instead of human format)
    
    ### `replace` — rewrite by pattern, dry-run by default
    
    ```bash
    # Dry-run preview (default — no files mutated)
    python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/
    
    # Actually apply
    python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/ --apply
    ```
    
    The helper:
    1. Validates both `pattern` and `rewrite` for hint-detectable mistakes.
    2. Runs pass 1 with `--json=compact` to collect matches and show a preview.
    3. If `--apply` is set, runs pass 2 with `--update-all` to mutate files.
    
    ### `scan` — run YAML rules
    
    ```bash
    # Discover sgconfig.yml from cwd and run all rules
    python3 scripts/ast_grep_helper.py scan src/
    
    # Run a single rule file
    python3 scripts/ast_grep_helper.py scan -r rules/no-console.yml src/
    
    # Apply auto-fixes
    python3 scripts/ast_grep_helper.py scan -U src/
    
    # CI-friendly GitHub annotations
    python3 scripts/ast_grep_helper.py scan --report-style short src/
    ```
    
    ### `validate` — offline pattern check (no `sg` call)
    
    Useful for CI lints, pre-commit hooks, and quick sanity checks:
    
    ```bash
    python3 scripts/ast_grep_helper.py validate '\w+' --lang ts
    # → exit 2: regex \w not supported. Use $VAR for identifiers.
    
    python3 scripts/ast_grep_helper.py validate 'console.log($MSG)' --lang ts
    # → exit 0: pattern looks plausible for ast-grep.
    ```
    
    ### `langs` / `doctor` / `install`
    
    ```bash
    python3 scripts/ast_grep_helper.py langs       # list 25 supported languages and aliases
    python3 scripts/ast_grep_helper.py doctor      # check ast-grep binary availability
    python3 scripts/ast_grep_helper.py install     # delegate to install.sh / install.ps1
    ```
    
    `new` and `test` subcommands proxy directly to `sg new` and `sg test`.
    
    ---
    
    ## Direct `sg` use (when the helper isn't enough)
    
    The helper is opinionated. For full control, drop to `sg`. The skill ships a CLI cheat sheet in `references/cli.md`. The minimal idioms:
    
    ```bash
    # Search
    sg run -p 'console.log($MSG)' --lang ts src/
    
    # Search with JSON for scripting
    sg run -p 'console.log($MSG)' --lang ts --json=compact src/ | jq '.[] | .file'
    
    # Rewrite, dry-run
    sg run -p 'console.log($MSG)' -r 'logger.info($MSG)' --lang ts --json=compact src/
    
    # Rewrite, apply
    sg run -p 'console.log($MSG)' -r 'logger.info($MSG)' --lang ts --update-all src/
    
    # Pattern from stdin (great for ad-hoc experiments)
    echo 'console.log("hi")' | sg run -p 'console.log($MSG)' --lang js --stdin
    
    # Debug a pattern that returns 0 matches
    sg run -p '<your pattern>' --lang <lang> --debug-query=ast --stdin <<< '<sample-code>'
    
    # Run YAML rules
    sg scan src/
    
    # Inline YAML rule (one-off)
    sg scan --inline-rules '
    id: no-todo
    language: TypeScript
    severity: warning
    rule: { pattern: TODO }' src/
    ```
    
    When using `sg` directly in a shell, **always single-quote patterns** so `$VAR` is not expanded by the shell.
    
    ---
    
    ## Decision tree — what to use, when
    
    ```
    USER asks for "find/rewrite/codemod"
    │
    ├─ structural pattern (function shape, call, class, import, control flow)
    │  └→ ast-grep (this skill)
    │
    ├─ text pattern (regex, alternation, character classes, file names)
    │  └→ rg / grep
    │
    ├─ semantic question (what variable does this refer to? does this throw?)
    │  └→ LSP tools, TypeScript compiler, Pyright, Semgrep with type inference
    │
    └─ multiple repos / federated search
       └→ a search engine + then ast-grep / rg / LSP per-repo
    ```
    
    If the user says "find all" or "every", default to ast-grep when the target is shaped (function, class, call, import, statement). Default to rg when the target is text (string content, comment, license header, file name, identifier substring).
    
    ---
    
    ## Always run dry-run first when rewriting
    
    A bad pattern silently rewrites the wrong thing. The helper's `replace` defaults to dry-run for this reason. The flow is:
    
    1. Search to confirm matches: `helper search '<pattern>' --lang X .`
    2. Dry-run rewrite: `helper replace '<pattern>' '<rewrite>' --lang X .` (no `--apply`)
    3. Inspect the dry-run summary: number of matches, files affected, the per-location preview.
    4. If wrong: refine pattern, go back to step 1.
    5. If right: `helper replace '<pattern>' '<rewrite>' --lang X . --apply`.
    
    Never apply a rewrite that you have not first dry-run.
    
    ---
    
    ## When `sg` returns 0 matches but you know the code is there
    
    In priority order:
    
    1. **Run `helper validate '<pattern>' --lang <lang>`** — catches regex misuse, missing function bodies, Python trailing colons.
    2. **Check `--lang`** — `sg` infers from extension; if you pass a `.tsx` file with `--lang ts` (not `tsx`), JSX won't parse.
    3. **Inspect the parsed pattern**: `sg run -p '<pattern>' --lang <lang> --debug-query=ast --stdin <<< '<sample>'`. If it shows `ERROR` nodes, the pattern is malformed.
    4. **Check the AST of the target file**: `sg run -p '$_' --lang <lang> --debug-query=cst path/to/file | head -40` — find the `kind` you're trying to match.
    5. **Try the playground**: <https://ast-grep.github.io/playground.html> — paste code + pattern, see what's happening.
    
    Do not blindly retry with variations. Each failure has a reason; surface it.
    
    ---
    
    ## When to use YAML rules vs inline `-p` patterns
    
    **Use inline `-p`** when:
    - One-off ad-hoc query.
    - The pattern is simple (no constraints, no fix template).
    - You're exploring.
    
    **Use YAML rules** (file under `rules/`, run via `sg scan`) when:
    - The pattern is reused (lint rule, codemod that runs in CI).
    - You need `constraints`, `transform`, complex `inside`/`has`, or composite logic.
    - You want auto-fix (`fix:` field).
    - You want to test the rule (snapshot tests via `sg test`).
    
    The full YAML rule schema is in `references/yaml-rules.md`. Project setup (`sgconfig.yml`, `ruleDirs`, `utilDirs`) is in `references/sgconfig.md`.
    
    ---
    
    ## Output discipline
    
    - `sg run --json=compact` produces an array of match objects: `{ file, range: {start, end}, text, replacement?, lines, language, ... }`. Pipe through `jq` for further processing.
    - Without `--json`, `sg` produces human-readable colored output suitable for terminals.
    - The helper's default output is human-readable (file:line:column + match preview). Pass `--json-out` for raw JSON.
    - The helper's `replace` always summarizes: number of matches, number of files, per-location preview.
    
    When summarizing for the user, **always include the count of files affected**, not just the count of matches. Users care about blast radius.
    
    ---
    
    ## Required reading (in order of priority)
    
    1. `references/patterns.md` — meta-variables, naming rules, strictness levels. Read when you're unsure why a pattern doesn't match.
    2. `references/pitfalls.md` — the failure-mode field guide. Read when 0 matches surprises you.
    3. `references/recipes.md` — copy-paste patterns by language. Read first when you start a new task.
    4. `references/cli.md` — `sg run`, `sg scan`, `sg test`, `sg new`, `sg lsp`. Read when the helper isn't enough.
    5. `references/yaml-rules.md` — YAML rule schema. Read when you outgrow inline patterns.
    6. `references/sgconfig.md` — project-level configuration. Read when you set up `sg scan` for a real project.
    7. `references/install.md` — per-OS install methods. Read only if `install.sh` / `install.ps1` fail.
    
    ---
    
    ## Invariants (do not break)
    
    - **Validate before searching.** When emitting a pattern programmatically, call `helper validate` first. It catches the regex-misuse class of mistakes that account for ~70% of "0 matches" debug sessions.
    - **Dry-run before applying.** Never run `sg run -r ... --update-all` without first inspecting the matches. The helper's `replace` enforces this by default.
    - **Two-pass writes.** When using `sg` directly to both preview and apply, run two invocations — `--json` ignores `--update-all`.
    - **Single-quote patterns in shell.** `'$VAR'` not `"$VAR"`. The shell expands `$VAR` to the empty string in double quotes, breaking the pattern.
    - **Pattern is code, not regex.** When the pattern would need `|`, `.*`, `\w`, or `[a-z]`, switch to `rg` instead. Don't try to force ast-grep into a regex shape.
    - **`--lang` is required for stdin.** When piping with `--stdin`, set `--lang` explicitly; `sg` cannot infer from extension.
    - **Linux: prefer `ast-grep` over `sg`** because `sg` collides with `setgroups`. The helper handles this; if you call `sg` directly, alias it: `alias sg=ast-grep`.
    
  • SOURCE 125 B · in bundle

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.