ISSUE 067  ·  17 NOVEMBER 2026 ELEN RSS
CodeCity
DEVELOPMENT № 0065

ast-grep: grep that understands code, not text

ast-grep: το grep που καταλαβαίνει κώδικα, όχι κείμενο

ast-grep: grep that understands code, not text

What it does

You have a project with thousands of files. You want to find every place where a function is called, or change an old pattern into a new one across all the code. You take the familiar text-search tool, type the word, and get back three kinds of things: real calls, references inside comments, and the same words inside strings. All three look like code. Only the first ones are.
The ast-grep solves the problem because it does not read text line by line. It reads the syntax tree — the AST, that is, the way the computer represents code, with nodes for calls, arguments, operators. You write the pattern as if you were writing code, and the tool searches for nodes with the same structure, ignoring spaces, line breaks, or alignment.
Variables that start with $, such as $A, stand in for any piece of code. The pattern $PROP && $PROP() finds every null check on a method call. The –rewrite parameter changes the piece that was found, and the scan subcommand applies rules written in YAML, like a linter with your own criteria.
Behind it is a four-year project written in Rust: github.com/ast-grep/ast-grep, MIT license, 16,319 stars, 482 forks, 54 open issues, first published on 1 July 2022. The latest release is 0.51.0, published on 15 October 2026 — 177 releases in total. In the npm registry, the package @ast-grep/cli was downloaded 7,576,712 times in the last month, from 19 September to 18 October 2026. The other package, @ast-grep/napi, which other tools use to talk to the same tree: 14,789,641 downloads in the same period.

What it does not do

Do not trust it when deep semantic analysis is needed: ast-grep works on syntax, not semantics. It will not tell you which call is actually the same function across different files if namespace or type analysis is needed. Do not ask it to resolve overloads, follow aliasing, or perform a full symbol reference like a language server with a type checker.
We ran rewrite rules and saw traps. The –rewrite changes AST pieces syntactically. It does not run tests, does not update imports automatically, and does not guarantee that the change is safe at runtime. Do not let an agent run scan -U before you first inspect the samples. Code with macros, preprocessor, or dynamic generation (eval, templating) often slips through or breaks.
Also, it is not a general text-search tool, nor does it replace a full IDE refactor tool. If you need a quick searching pass through logs or a single hand-to-hand name, plain grep or your editor is simpler and safer.

Who it is for

For anyone who has code and wants to change it in bulk without changing it wrongly. One rename that has to happen in five hundred places. An old call pattern replaced by a new one. A rule that forbids the use of a function and you want to see where it is violated.
Its big audience is elsewhere, though. It is code agents. A helper working in a repository keeps searching for things and often rewrites files. There ast-grep becomes its eyes: you give it one command, and it gets exact locations instead of noise. You do not need to know Rust, nor set up anything heavy — it is a single binary.
It makes no sense when you are searching text, not code. In a log file, in documentation, in a list of names, plain grep is the right tool and faster. And it makes no sense for a single change that you do by hand in ten seconds.

Installation

The npm route

From any folder, once:

npm i -g @ast-grep/cli@0.51.0

In our test it took 6.246 seconds. Check that it was installed:

ast-grep –version

The answer was ast-grep 0.51.0. The package has only one dependency, detect-libc.

The zip route for Windows

Download the Windows file from the repository releases page. It is 16,249,102 bytes, that is 16.2 MB, and inside it hides a 54,041,600-byte binary (51.5 MB). It has no installer, does not touch PATH, and does not need a restart. Unpack it, go into the folder and ask for the version:

ast-grep –version

The answer was again ast-grep 0.51.0. This route is the cleanest for testing: it installs nothing on the system and leaves nothing behind when you delete it.
In both cases the same applies: it asks for no key, goes out to no network, and has no telemetry.

Use in every LLM

First the important thing, because this is where a misunderstanding hides. ast-grep is not an MCP server. You do not “declare” it to an assistant the way you declare a tool server. In version 0.51.0 its subcommands are run, scan, test, new, lsp, outline and completions — there is no mcp subcommand (CLI reference).
So using it from an agent happens in two ways. The first, and the most common, is the shell: the agent gives the command and gets back text or JSON. The second is the language server, which the VS Code extension uses and gives diagnostics inside the editor as you type, along with quick fixes.
The commands that follow are shell commands and we ran them as such. What we did not run: we did not drive the Codex CLI agent or Claude Code from start to finish, because we do not have those programs on this machine — we do have Cursor, but even there I did not open an agent session. In other words: the commands work, the behavior of each assistant toward them is my own estimate from the operating flow.

Claude Code

In Claude Code the route is the shell tool. You give the agent permission to run the command, and then it asks for it itself in the conversation. Structured search, with output a machine can read:

ast-grep run -p 'console.log($A)' -l js –json

Mass correction from rules, after you first see what will change:

ast-grep scan -U

Check that the rule matches what you think:

ast-grep test

One comment here, and I explain it in the traps section: scan reads rules from a configuration file and a rules folder, and -U applies the changes without asking. It is not a command to leave loose in front of an assistant before you check the rules.

Codex CLI

In Codex CLI the route is the same in spirit — shell — with the difference that Codex has its own safety limits on what it allows to run. The commands are the same:

ast-grep run -p '$A && $A()' –rewrite '$A?.()' -l ts

This shows the difference it would make, without making it. When you agree, you add the application. And to get a structured list instead of text:

ast-grep run -k call_expression -l ts –json=stream

The -k searches by node kind instead of full pattern, useful when you want the opposite — not “this call” but “every call.”

Cursor

In Cursor you have both routes together. The agent has a terminal and runs the same commands. And because Cursor is VS Code in another outfit, it accepts the ast-grep extension, which talks to the language server and gives you underlines and fixes inside the file.
From the terminal, a quick map of a folder — what is inside, without opening it:

ast-grep outline src/

And a search inside a Python project:

ast-grep run -p 'foo($A)' -l py –json

For the extension route, the path is: open the extensions panel, search for ast-grep, install it, and then the extension loads the command-line tool’s own language server. We did not test this part — I did not open an extension inside Cursor.

Where it wins, where it loses

It wins at the first, big problem: it finds code and does not catch what only looks like code. The test numbers say so. And it wins in speed, against the language that hosts it, Rust: 94,025 files in 17.119 seconds.
It wins because it is a single binary with no dependencies and no network. Download, unpack, run. It asks for no key, sends nothing out, has no telemetry.
And it wins because it does not bring anything into the assistant session. It is not an MCP server, it does not load tool schemas into the context. One command, one answer.
Now where it loses and what you should watch. Five things, in order of seriousness.
First, sg. You will see it in old articles, old comments, old examples. It is the tool’s old name and has been retired; in addition, on Linux it clashes with the built-in setgroups command. The correct command is ast-grep. If you copy an example with sg, you may not find the program at all.
Second, -U writes everywhere it looks. It does not ask and does not stop. In our test, one copied folder inside the project doubled the changes: 10 instead of 5. The mistake is not the tool’s, it is the file list you gave it. Before -U: inspect the rules, inspect the ignore patterns, run plain scan without -U and read the diff.
Third, ast-grep test does not pass on the first run. The mechanism works with a baseline snapshot. In a new rule, the first pass comes out FAIL because the snapshot does not exist yet. It needs –update-all to write it first, and then the test is a real test. Whoever sees FAIL and thinks the rule is wrong will chase ghosts.
Fourth, governance hangs on one person. The project has 97 contributors, but the main maintainer has 2,812 commits, while the next person has 12 (GitHub contributors API, today). It is a mature four-year project, with sponsors, and no company behind it. It is not a scandal, it is a risk you know: if something happens to him, the project has no second steering wheel.
Fifth, the users it claims. The documentation page says it is used by SWC, Shopify Hydrogen, CodeRabbit, Codemod, Dify and Modern.js. I am relaying this as the project’s claim, not as a fact we checked — I did not go into each of those repositories to verify it.
And one difference from what we have covered so far. Context7 gives documentation, Basic Memory keeps notes — both answer “what does this mean.” ast-grep answers “where is this inside the code,” and in a form a machine can read. It is a different kind of tool, and it enters exactly when an agent raises its hand to change code.

Test

What follows we ran today on Windows 11, on a Dell Inspiron 3576, without a graphics card.
The npm installation took 6.246 seconds, and the version answered ast-grep 0.51.0. Disk: 16.2 MB download, 51.5 MB after unpacking.
The experiment that matters, first. I made a file where the word console.log appears deliberately in three wrong places: inside a comment, inside a string, and as an object key — and in one correct place, as a real call. Plain grep found 4 spots. ast-grep found 1: the only real call.
The same, in a sample of four files. Plain grep gave 8 spots, ast-grep 5. That is, 37.5% of what a text replacement would “fix” would be damage — three of the eight changes would hit comments, strings, or keys.
Second, mass correction with a rule:

ast-grep scan -U

Answer: “Applied 5 changes” in 0.070 seconds. Five out of five correct.
Third, rule test:

ast-grep test

The first pass came out FAIL, because there was no baseline snapshot. With –update-all the snapshot was written, and the second pass came out PASS: “1 passed; 0 failed” in 0.078 seconds.
Fourth, scale. I scanned 94,025 code files, in JavaScript, TypeScript and Python, in 17.119 seconds. As long as one sip of coffee.
And the trap that matters, because it is the exact one. I put a copied folder with the same files into the project and ran scan -U again. The changes doubled: 10 instead of 5, because the tool saw the same files twice. It destroyed nothing — the files were copies — but the lesson cost a minute and could have cost a repository.
What we did not run, and I say it clearly: we did not run any agent session inside Claude Code, Codex CLI or Cursor. We do not have the first two on the machine, and in Cursor I did not open a session. The commands I gave above run in the shell, and that is the part that was tested.

What it costs

Money: zero. MIT license, verified both in the repository and on npm. There is no subscription, no key, no per-use charge.
Weight: 16.2 MB download, 51.5 MB on disk after unpacking. The npm package has one dependency, detect-libc, which exists only so the tool can tell which system it is running on.
Context and tokens: here is the good news, and I say it as an estimate from the operating flow, not as a measurement. Because it is not an MCP server, it loads no tool schema into the assistant session. You do not pay anything until you call it, and when you call it you pay only for the output you chose: a line of text, or a bit of JSON with the locations you asked for. I do not count tokens here because there is no tool entry to count.
Hidden cost: the learning time. –rewrite and scan want you to learn the logic of patterns — where the $ goes, what -k catches, what “strictness” means in matching. It is not hard, but it is not the first time either. And there is the safety around -U, which costs discipline: look at the diff before applying it.
Public numbers, with their source. On npm, @ast-grep/cli has 7,576,712 downloads per month from 19 September to 18 October 2026, with 177 releases in total, the latest on 15 October 2026. On GitHub, 16,319 stars, 482 forks, 54 open issues, repository open since 1 July 2022. The fact that the napi library has more than twice the downloads of the command-line tool says something interesting: ast-grep’s bigger audience does not run it, it calls it from other tools.

Verdict

ast-grep does a job that everyone thinks they are doing with grep, and they are not. In our experiment, plain grep gave four spots and ast-grep one — the only real call. Across four files, 37.5% of the changes a text replacement would make would be damage.
It is small, fast and free. 94,025 files in 17.119 seconds, 16.2 MB download, zero euros, zero key, zero telemetry. For a code agent it is almost an ideal tool: it does not load the context with schemas, but it gives it a pair of eyes that are not fooled by comments.
The objections are specific. sg has been retired and the confusing name will trip you once. -U writes wherever you tell it to, and in our test the copied folder doubled the changes. test wants a snapshot first. And governance rests on one person, with 2,812 commits against 12 from the next.
If you work on code — alone or with an agent — install it today. It has no cost, no installation risk, and it answers a question you will ask tomorrow. Before letting -U loose on a live repository, run it once without it and read what would change.
Score: 9.0/10.

See also

Three more from the same category:

ty: Astral’s type checker that catches the mistake before it runs
cf: Cloudflare’s new CLI that does not guess flags
DBHub — two tools and one connection string text, and your assistant asks your database

Sources: repository https://github.com/ast-grep/ast-grep · command-line package https://www.npmjs.com/package/@ast-grep/cli · napi library https://www.npmjs.com/package/@ast-grep/napi · documentation https://ast-grep.github.io/ · CLI reference https://ast-grep.github.io/reference/cli.html · quick start https://ast-grep.github.io/guide/quick-start.html · contributors https://api.github.com/repos/ast-grep/ast-grep/contributors