Ast Grep

---
name: ast-grep
description: "Search, outline, and rewrite code structurally with ast-grep rules."
license: MIT
metadata:
  kind: task
  author: Médéric HURIER (Fmind)
  source: github.com/fmind/dot/tree/main/skills/ast-grep
  created: "2026-09-03"
  updated: "2026-10-05"
---

# ast-grep

Structural code search and rewrite: a pattern is real code with meta-variables, matched against the syntax tree. A call-expression pattern distinguishes a call from similar text inside a string or comment; string and comment nodes can also be matched deliberately. Use it where `rg` gives false positives; plain text search stays with `rg`.

## Commands

```bash
ast-grep outline -l python src/                                                 # symbols, imports, and members per file
ast-grep run -p 'print($$$ARGS)' -l python src/                                      # scope search to the relevant source
ast-grep run -p 'print($$$ARGS)' -r 'logger.info($$$ARGS)' -l python src/             # dry run: prints the diff, changes nothing
ast-grep run -p 'print($$$ARGS)' -r 'logger.info($$$ARGS)' -l python --update-all src/ # apply after reviewing the dry run (-i to confirm per hunk)
ast-grep run -p 'os.getenv($KEY)' -l python --json=compact src/                       # structured output after narrowing paths
ast-grep scan                                                                    # every rule in sgconfig.yml
ast-grep scan -r rules/no-print.yml --format github                              # one rule file; GitHub annotations in CI
```

## Workflow

1. **Write the pattern as code**: `$NAME` matches one node, `$$$NAME` a sequence (arguments, statements), `$_` a node without binding; always pass `-l <lang>` so the pattern parses in the right grammar, and use `--debug-query=ast` when a pattern that should match does not.
1. **Search first**: map unfamiliar files with `ast-grep outline` before reading full source; pass the relevant path or `--globs`; use `--files-with-matches` when only filenames are needed, then read selected matches with `-C 2`. Use JSON only for structured processing. Widen scope deliberately, and use `--no-ignore vcs` (or `hidden`; the flag requires a value) only when skipped files are relevant.
1. **Rewrite in two steps**: add `-r` to see the diff, then `--update-all` (or `-i` for an interactive session); captured meta-variables are reused in the replacement.
1. **Promote to a rule**: for a lint or a repeated refactor, `ast-grep new project` scaffolds `sgconfig.yml` and `rules/`; a rule file has `id`, `language`, `rule` (`pattern`, `kind`, `inside`, `has`, `not`), optional `fix`, `severity`, and `message`; `ast-grep test` runs its `valid` and `invalid` cases.
1. **Wire into the gate**: run `ast-grep scan` inside `check:lint` (see [mise](../mise/SKILL.md)) so hooks and CI apply the same rules.

## Gotchas

- **Meta-variables are uppercase**: `$a` is plain text; `$A`, `$ARGS`, `$_` are meta-variables.
- **Pattern must be a complete node**: `foo(` does not parse; match `foo($$$)` and narrow with `--selector`.
- **Rewrites replace the whole node**: `-r` replaces the whole matched node, not a substring inside it.
- **Syntax is not name resolution**: inspect imports, aliases, and shadowed names before rewriting; identical syntax can refer to different functions.
- **Pass `-l` for inline patterns**: pass `-l python` for inline patterns; under `scan`, the `.py` extension selects the grammar.

## Official Skills

Upstream: `ast-grep/agent-skill` ships `ast-grep` (structural search) and `ast-grep-outline` (codebase map); preview the same-name upstream `ast-grep` instead of installing it ([vendor-skill policy](../agent-project/references/vendor-skills.md#name-collisions)); the rest follow the same policy.

## Documentation

- [ast-grep guide](https://ast-grep.github.io/guide/introduction.html) · [Pattern syntax](https://ast-grep.github.io/guide/pattern-syntax.html) · [Rule reference](https://ast-grep.github.io/reference/rule.html) · [Languages](https://ast-grep.github.io/reference/languages.html)
- Releases: [ast-grep](https://github.com/ast-grep/ast-grep/releases) · [changelog](https://github.com/ast-grep/ast-grep/blob/main/CHANGELOG.md)
- Companion skills: [repository-maintenance](../repository-maintenance/SKILL.md) (repository simplification), [python-stack](../python-stack/references/foundation/GUIDE.md) (Python quality gate).