Skip to the content
Know your tech before you buy it. Makers: get listed from $49/mo

ast-grep

ast-grep.github.io

  • Free plan
  • Windows
  • macOS
  • Linux
  • Web
  • Browser extension
  • API

What ast-grep is

ast-grep is a free, open-source tool for searching, linting, and rewriting code by matching patterns against syntax tree nodes. Its CLI can scan many files, preview and apply rewrites interactively, and run configurable lint rules with error, warning, info, and hint severity. YAML rules can combine pattern, kind, regex, relational, and composite conditions, and CLI commands support creating and testing rules, including snapshot-based tests. The project says it supports more than 20 languages and can load custom languages. A JavaScript API lets programs inspect and change syntax trees, while a WebAssembly API supports browser and other WASM environments. The online playground allows users to try patterns without installing the tool. Editor support includes a VS Code extension and language-server setups, with guides for Neovim and Emacs. The FAQ notes that some advanced static-analysis information is not supported. A single rule cannot target multiple languages at once; the project suggests using a superset language with languageGlobs or separate rules for each language.

Who it suits

ast-grep suits developers who need structural code search, custom lint rules, or repeatable rewrites across a codebase. It also fits teams seeking editor integrations or APIs for syntax-tree operations.

Good to know, and what to watch

  • Matches patterns against syntax tree nodes.
  • Supports more than 20 languages.
  • Interactive rewrite preview and application are available.
  • Includes JavaScript and WebAssembly APIs.
  • Online playground works without local installation.
  • Some advanced static-analysis information is unsupported.
  • A single rule cannot target multiple languages.
  • LSP lint diagnostics require an sgconfig.yml project file.

ast-grep

Free

Open source

Getting started

  1. Open the ast-grep website or online playground
  2. Install the CLI through npm, Cargo, Homebrew, MacPorts, Nix, or pip
  3. Build from source if preferred
  4. Create or load YAML rules
  5. Connect the VS Code extension or a documented language-server setup
  6. Add sgconfig.yml when language-server lint diagnostics are needed

Limits to check

ast-grep has no paid tier or trial requirement. Its FAQ notes unsupported advanced static-analysis information, and a single rule cannot target multiple languages; language-server lint diagnostics require an sgconfig.yml project file.

The Club's review

ast-grep is an open-source code tool for developers who need to search, lint, or change code by its structure across a codebase. It is especially useful when teams want reusable rules and broad refactors without relying on exact text matches. Its limits in advanced static analysis make it a complement to deeper analysis tools, not a replacement.

Overview

Instead of matching source text, ast-grep matches patterns against syntax-tree nodes. That lets a search target code structure across variations in formatting, and helps avoid the false matches that blunt text searches can produce. The CLI can preview and apply changes interactively; the project describes parallel Rust processing for searches and replacements across thousands of files. This makes it a good fit for repeatable codebase-wide work, though it should not be mistaken for a tool that understands every behavior or relationship in a program.

Key features

Search, rewrite, and lint

The scan command runs configurable AST-pattern rules and reports severities ranging from error to hint. That gives teams a way to enforce code-shape conventions and surface findings at different levels of urgency. Interactive rewrite previews help reviewers inspect a proposed transformation before applying it. These capabilities suit structural refactors and targeted checks; they are less suitable when a rule depends on advanced static-analysis information that ast-grep does not support.

Custom rules and testing

Rules are written in YAML and can combine pattern, kind, regex, relational, and composite matching conditions. The CLI includes commands to create and test rules, including snapshot-based testing. That combination supports reusable rules with a way to check their expected matches, but teams still need to design and maintain rules for their own code. A single rule cannot target multiple languages at once: use a superset language with languageGlobs or maintain separate rules for each language.

Languages, editors, and APIs

The project says it supports more than 20 languages and can load custom languages, a broad base for polyglot repositories. Its online playground lets users try patterns and rewrite rules without a local installation. Editor support includes a VS Code extension and language-server integrations for editors such as Vim and Neovim; the server publishes diagnostics and diagnostic code actions, with lint diagnostics requiring an sgconfig.yml project file. JavaScript and WebAssembly APIs extend syntax-tree inspection and changes to programs and browser or other WASM environments. The CLI is distributed through npm, Cargo, Homebrew, MacPorts, Nix, and pip, and can also be built from source.

Security examples and support

The example catalog includes rules for issues such as a Go JSON tag vulnerability and C/C++ format-string risks. These examples show how structural rules can target security-relevant code patterns, but do not turn ast-grep into a full security-analysis suite. Users can seek community help through GitHub, Discord, Stack Overflow, and Reddit.

Pricing

ast-grep is open source and free. Its ast-grep plan costs nothing, and there is no free trial because the project is already free to use. There are no paid tiers or seat-based pricing to weigh; the practical trade-off is that users take on the work of setting up and maintaining their rules and workflows.

Platforms

ast-grep is available across Linux, macOS, and Windows, with API and extension support and a web playground. Its codebase indexing scope and self-hosted deployment suit teams that want to run structural search within their own development workflow rather than rely on a hosted code-analysis service.

Who it's for

Choose ast-grep if you need structural code search, linting, or repeatable rewrites across a codebase, especially in a repository spanning multiple languages. It is also a strong option for developers who want to author YAML rules, test them, and connect findings to an editor or programmatic API. Look elsewhere or pair it with another tool when the job depends on advanced static analysis, or when one shared rule must cover multiple languages.

Pros and cons

Pros

  • Structural matching targets syntax-tree nodes, making it more precise for code-shaped searches and rewrites than plain text matching.
  • Interactive previews, configurable lint severities, and rule-testing commands support a controlled, repeatable workflow.
  • More than 20 supported languages, custom-language loading, editor integrations, and JavaScript and WebAssembly APIs offer several ways to fit it into development work.
  • Free, open-source distribution and multiple package managers make adoption possible without a subscription.

Cons

  • It lacks some advanced static-analysis information, limiting checks that require more than syntax structure.
  • Rules cannot target multiple languages at once, so polyglot teams may need separate rules or a superset language configuration.
  • Lint diagnostics from the language server require an sgconfig.yml project file, adding setup for editor-based linting.

Alternatives

For a different code-search approach, Semantic Designs Source Code Search Engine has a free evaluation version capped at 10,000 lines and supports Java, COBOL, C++, and pseudo-code; consider it when those languages and that evaluation scope fit better. Sourcebot is a freemium API, self-hosted, and web option, while Code Search offers a free Community plan with unlimited users, full-text search, repository find-and-replace, a CLI, and an MCP server. Choose either when those search and deployment details better match your workflow than AST-pattern rules.

OpenGrok is a free, open-source alternative for readers considering another code-search project. Chatterbox TTS is an unrelated text-to-speech option. Code Fundi is a freemium alternative with a paid Dev plan at $21 a month. searchcode is free during beta, and sqry is a free, local, MIT-licensed option for Linux, macOS, and Windows.

Browse more Code Search Tools or Code Refactoring Tools.

Verdict

ast-grep is a strong choice for developers who need free, reusable structural search, linting, and rewrites across a codebase. Its syntax-aware rules and interactive transformations are the main reasons to choose it; look elsewhere or pair it with deeper analysis when syntax-level matching is not enough, or when rules must span languages in one definition.

The verdict

ast-grep offers structural search, linting, and rewrite tools alongside APIs and editor support. Account for its stated static-analysis and multi-language rule limits when designing workflows.

Questions people ask

How much does ast-grep cost?

ast-grep is free and open source. Its listed plan costs nothing.

Which languages does it support?

The project says ast-grep supports more than 20 programming languages and can load custom languages.

Can I try it without installing anything?

Yes. The online playground lets you try patterns and rewrite rules in a browser.

Which editors integrate with ast-grep?

There is an official VS Code extension and language-server support, with documented setups for Vim, Neovim, and Emacs.

Can rules target several languages?

A single rule cannot target multiple languages. The FAQ recommends a superset language with languageGlobs or separate rules for each language.

What APIs are available?

The JavaScript API can inspect and change syntax trees, and the WebAssembly API supports browsers and other WASM environments.

What the maker publishes

APIs
ast-grep provides a JavaScript API for programmatically inspecting and changing syntax trees, plus a WebAssembly API for browsers and other WASM environments. source
Code rewriting
The CLI can interactively preview and apply rewrites to matching code. source
Custom rules
Rules are written in YAML and can combine pattern, kind, regex, relational, and composite matching conditions. source
Distribution
The CLI is distributed through npm, Cargo, Homebrew, MacPorts, Nix, and pip, and can also be built from source. source
Install methods
The CLI is distributed through npm, Cargo, Homebrew, and MacPorts, with source builds also available. source
Integrations
The documentation describes editor integrations, including a VS Code extension and language server support for editors such as Vim and Neovim. source
Languages
The project says it supports 20+ languages and allows custom languages to be loaded. source
Language support
The site says ast-grep supports 20+ programming languages and can load custom languages. source
Limits
The FAQ says ast-grep does not currently support some advanced static analysis information. source
Linting
The scan command runs configurable AST pattern rules and supports severity levels including error, warning, info, and hint. source
Lint rules
Users can define custom lint rules with AST patterns and receive error reporting. source
LSP capabilities
The language server publishes diagnostics and supports diagnostic code actions; linting diagnostics require an sgconfig.yml project file. source
Notable limitation
A rule cannot target multiple languages at once; the FAQ recommends a superset language with languageGlobs or separate rules for each language. source
Other editor integrations
The editor guide documents setups for Neovim and Emacs, plus community integrations for coc.nvim, Telescope, and grug-far.nvim. source
Pattern search
It matches code patterns against syntax tree nodes rather than searching source text. source
Performance
The site describes search and replace across thousands of source files as powered by parallel Rust. source
Programmatic API
The JavaScript API lets programs inspect and change syntax trees using JavaScript. source
Publisher
The site credits Herrington Darkholme in its copyright notice. source
Purpose
ast-grep is a fast, polyglot tool for structural code search, linting, and rewriting at scale. source
Rule testing
The CLI includes commands to create and test rules, with snapshot-based test options. source
Search and rewrite
It uses code patterns and abstract syntax trees to find and modify code across many files, with an interactive rewrite mode. source
Security use
The example catalog includes rules for detecting security issues, such as a Go JSON tag vulnerability and C/C++ format string risks. source
Support
The project directs users with questions or issues to GitHub or Discord and also points to Stack Overflow and Reddit. source
Support channels
The site links to Discord, Stack Overflow, and Reddit community channels. source

Checked against the maker's pages on 4 Oct 2026.