What is ast-grep?
ast-grep finds code by its structure rather than its text. You write a pattern that looks like ordinary code, such as `$A && $A()`, with placeholders for the parts that vary, and it matches every place in a codebase with that shape, whatever the spacing or variable names. The same patterns drive YAML lint rules (`ast-grep scan`), rule tests and rewrites, applied in bulk or one by one with `--interactive`. It parses with tree-sitter and supports 28 languages out of the box, from Bash and C to TypeScript and Zig.
The project, led by Herrington Darkholme, is MIT licensed, written in Rust and has about 16,600 GitHub stars; release 0.51.2 shipped on 11 November 2026. It installs from Homebrew, npm, pip, cargo, MacPorts or Nix, and also ships JavaScript, Python and WebAssembly APIs, a language server for editors and a JSON output mode. For coding agents there is an `outline` command (an alpha preview since 0.44.0), an official agent skill and an experimental MCP server.
Is ast-grep worth it?
Text search is the wrong tool for most refactors, and agents make the mistake faster than people do. A regex that rewrites a function call also rewrites the same words in a comment, a string and a variable that happens to share the name. ast-grep parses the file first, so a pattern only matches real code of that shape. That is why it has become a common dependency in agent setups: npm counted about 9.6 million downloads of @ast-grep/cli in the 30 days to 12 November 2026, a figure that includes CI and transitive installs, not only people typing commands.
The design keeps patterns readable. Instead of learning a query language, you write code with metavariables, and add YAML rules (inside, has, not, any) when a pattern alone cannot say enough. Rules can carry a fix, a severity and tests, which turns one-off searches into a project linter. The release cadence is steady, with 0.51.1 on 2 November and 0.51.2 nine days later, and the history has more than 100 contributors.
The catch: it only sees syntax. The FAQ says plainly that it has no scope, type, control-flow, data-flow or taint analysis, so it cannot find a variable of a given type or trace user input to a database call. For security rules of that kind Semgrep or CodeQL go further. Patterns must also be code that tree-sitter can parse, which trips people up with fragments such as a lone JSON key, and on Linux the short `sg` alias clashes with the system's setgroups command. The MCP server is labelled experimental and runs through Python and uv, so most agents are better served by the CLI and the skill.
Our take: think of ast-grep as grep that knows where a function call starts and ends. Let the agent use it for every search and rewrite that has a shape, and keep a type-aware tool for questions about meaning.
Where it earns its place
A platform engineer on a large TypeScript monorepo
Replace a deprecated logging call everywhere without touching comments or strings
Write one pattern with a fix, preview with `ast-grep run --interactive`, then apply it across the tree. It runs locally in seconds on most repos and costs nothing; anything that depends on types still needs the compiler.
A tech lead enforcing house rules in CI
Block new code that calls an internal API the wrong way
Add YAML rules to an sgconfig.yml project, give each a test case, and run `ast-grep scan` in the pipeline. Rules live in the repo and are reviewed like code, with no licence fee.
A developer running Claude Code on an unfamiliar codebase
Have the agent find and edit code by structure instead of by regex
Install the CLI and the official agent skill so the agent writes ast-grep rules, and let `ast-grep outline` list a file's symbols before it reads the whole file. Fewer stray edits; outline is still an alpha preview.
Before you commit
- Setup
- `brew install ast-grep`, `npm i @ast-grep/cli -g`, `pip install ast-grep-cli` or `cargo install ast-grep --locked`; a first search takes a minute. `ast-grep new` scaffolds a rule project.
- Integrations
- 28 built-in languages with custom ones via tree-sitter, a language server for VS Code and other editors, JSON output, JavaScript (napi), Python and WebAssembly APIs, an online playground, the ast-grep/agent-skill plugin and the experimental ast-grep-mcp server.
- Data and privacy
- Runs entirely on your machine against local files; no account or network service is involved. MIT licence.
- Cost at scale
- Free, with no paid tier. The maintainer accepts GitHub Sponsors; the cost at scale is writing and testing the rules.
- Limits
- Syntax only: no type, scope, control-flow, data-flow or taint analysis. Patterns must be parseable code. `outline` is an alpha preview whose language coverage may change. About 46 open issues and pull requests at last check.
What’s good
- Patterns are written as ordinary code with placeholders
- 28 built-in languages through tree-sitter
- Search, lint rules with tests, and rewrites in one binary
- JavaScript, Python and WebAssembly APIs plus a language server
What’s not
- No type, scope or data-flow analysis
- Patterns must parse as valid code, which confuses newcomers
- `sg` alias clashes with a Linux system command
- MCP server is still experimental
Best for
Developers and coding agents that need precise, repeatable searches and codemods across a large codebase without writing a compiler plugin.
ast-grep alternatives
ast-grep: common questions
- Is ast-grep worth it?
- ast-grep is the structural search tool to hand a coding agent before it reaches for sed, as long as nobody mistakes its syntax matching for semantic analysis. We rate it 4.5 out of 5.
- How much does ast-grep cost?
- Free and open source (MIT).
- What are the downsides of ast-grep?
- No type, scope or data-flow analysis; patterns must parse as valid code, which confuses newcomers; `sg` alias clashes with a Linux system command; mCP server is still experimental.
- Who is ast-grep best for?
- Developers and coding agents that need precise, repeatable searches and codemods across a large codebase without writing a compiler plugin.
- How much does ast-grep cost for a team or in production?
- Free, with no paid tier. The maintainer accepts GitHub Sponsors; the cost at scale is writing and testing the rules.
- Is ast-grep safe for company data?
- Runs entirely on your machine against local files; no account or network service is involved. MIT licence.
- What are the best ast-grep alternatives?
- The closest alternatives we have reviewed are grepai, Repowise and jevgrep.
Answers checked Nov 13, 2026.
Make ast-grep? Show this rating on your site
