ast-grep

ast-grep is a free, open-source tool for developers who need to find and change code by structure rather than by text. It suits teams building repeatable code checks or refactors across a codebase. Its strongest case is syntax-aware work across many languages; it is not a replacement for advanced static analysis.

Overview

Because ast-grep matches patterns against syntax-tree nodes, it can target code forms without depending on an exact textual match. That makes it useful when a broad text search would catch irrelevant code or miss formatting variations. The CLI supports previewing and applying rewrites interactively, and the project describes parallel Rust processing for searches and replacements across thousands of source files.

Structural matching gives developers control over what a rule targets, but it does not reveal every property of program behavior. The FAQ says some advanced static-analysis information is not supported, so teams needing deeper analysis should look elsewhere or use another tool alongside it.

Key features

Search, rewrite, and lint

The scan command runs configurable rules against syntax patterns and reports severities including error, warning, info, and hint. This makes ast-grep useful for recurring code-shape checks as well as one-off searches. Interactive rewrite preview is a sensible safeguard for broad changes, though the rules still need to express the intended code structure accurately.

Custom rules and testing

Rules are written in YAML and can combine pattern, kind, regex, relational, and composite conditions. CLI commands help create and test rules, including snapshot-based testing. That combination suits teams that want reusable checks they can validate before applying across a codebase; it asks more of users than a ready-made search box because they must define the rule logic.

Languages and integrations

The project says it supports more than 20 languages and can load custom languages. A rule cannot target multiple languages at once, however; users must use a superset language with languageGlobs or maintain separate rules. That is a meaningful cost for teams seeking one shared rule set across heterogeneous repositories.

The VS Code extension provides a UI for the CLI and a client for the language server. The server publishes diagnostics and diagnostic code actions, while lint diagnostics require an sgconfig.yml project file. Documentation also covers Neovim and Emacs setups and community integrations for coc.nvim, Telescope, and grug-far.nvim.

APIs and playground

The JavaScript API lets programs inspect and change syntax trees, while the WebAssembly API supports browsers and other WASM environments. An online playground lets users try patterns and rewrite rules without installing the tool locally. These options make ast-grep useful beyond terminal workflows, though the core value remains its rule-based structural matching.

Pricing

ast-grep is free and open source, with a free plan priced at free. There is no free trial because the tool is already free. The plan is a practical fit for individual developers and teams that can run and manage the software themselves; there are no paid plan tiers or stated seat caps to weigh against a subscription.

The CLI is distributed through npm, Cargo, Homebrew, MacPorts, Nix, and pip, and can also be built from source. The deployment model is self-hosted, so users should expect to manage their own environment rather than rely on a hosted service.

Platforms

ast-grep supports Linux, macOS, and Windows, alongside API, extension, and web access. Its CLI can be installed through several package managers, and editor integrations connect it to IDE and language-server workflows. The browser playground and WebAssembly API offer ways to work without a local CLI installation.

Who it's for

ast-grep is best for developers who need repeatable structural searches, lint rules, or large-scale code rewrites and are comfortable working with syntax patterns. It can also suit teams that want to encode code-shape checks in rules and test those rules before applying them broadly. Users who need advanced static-analysis information, or a single rule that spans several languages, should consider another approach.

Pros and cons

Structural matching: Patterns target syntax-tree nodes, which is more selective than matching source text when code formatting or surrounding structure matters.

Reusable, testable rules: YAML conditions and CLI rule-testing commands help teams maintain repeatable checks instead of relying only on ad hoc searches.

Broad access: CLI, editor integrations, JavaScript and WebAssembly APIs, and a browser playground accommodate different workflows.

Language-specific rule work: A rule cannot target multiple languages at once, which adds maintenance for mixed-language codebases.

Analysis boundary: Some advanced static-analysis information is unsupported, limiting its fit for checks that depend on deeper program analysis.

Alternatives

Code Search is worth considering when repository-wide full-text search, find-and-replace, and SCIP code intelligence matter more than ast-grep's syntax-pattern rules; its Community plan is free with unlimited users and includes a CLI and MCP server.

OpenGrok is another free, open-source option for readers comparing code search tools. Sourcebot offers a free Basic plan and a free trial for code search. sqry is a free, local-running open-source option for Linux, macOS, and Windows. Shebe is a free local code-search option. Understand may suit readers seeking a freemium alternative with a paid annual subscription; its listed annual plan is $100,120 a year with a minimum term of 12 months. Code Fundi is a freemium alternative with a Dev plan at $21 a month, including 5,000 Credits/Mo and 10 Private Repo Indexes. Hound is another free code-search option.

For broader comparisons, see Code Search Tools and Code Refactoring Tools.

Verdict

Choose ast-grep if you want a free, self-hosted way to search, lint, and rewrite code by syntax structure, with rules you can test and use from the CLI, editors, or APIs. Its main reason to look elsewhere is equally clear: teams that need advanced static analysis or a single rule across multiple languages will have to choose a different tool or supplement it.