AST-Grep Find

Structural code search that understands syntax. Find patterns like function calls, imports, class definitions - not just text.

When to Use

• Find code patterns (ignores strings/comments)

• Search for function calls, class definitions, imports

• Refactor code with AST precision

• Rename variables/functions across codebase

Usage

Search for a pattern

uv run python -m runtime.harness scripts/ast_grep_find.py
--pattern "import asyncio" --language python

Search in specific directory

uv run python -m runtime.harness scripts/ast_grep_find.py
--pattern "async def $FUNC($$$)" --language python --path "./src"

Refactor/replace pattern

uv run python -m runtime.harness scripts/ast_grep_find.py
--pattern "console.log($MSG)" --replace "logger.info($MSG)"
--language javascript

Dry run (preview changes)

uv run python -m runtime.harness scripts/ast_grep_find.py
--pattern "print($X)" --replace "logger.info($X)"
--language python --dry-run

Parameters

Parameter Description

--pattern

AST pattern to search (required)

--language

Language: python , javascript , typescript , go , etc.

--path

Directory to search (default: . )

--glob

File glob pattern (e.g., **/*.py )

--replace

Replacement pattern for refactoring

--dry-run

Preview changes without applying

--context

Lines of context (default: 2)

Pattern Syntax

Syntax Meaning

$NAME

Match single node (variable, expression)

$$$

Match multiple nodes (arguments, statements)

$_

Match any single node (wildcard)

Examples

Find all function definitions

uv run python -m runtime.harness scripts/ast_grep_find.py
--pattern "def $FUNC($$$):" --language python

Find console.log calls

uv run python -m runtime.harness scripts/ast_grep_find.py
--pattern "console.log($$$)" --language javascript

Replace print with logging

uv run python -m runtime.harness scripts/ast_grep_find.py
--pattern "print($X)" --replace "logging.info($X)"
--language python --dry-run

vs morph/warpgrep

Tool Best For

ast-grep Structural patterns (understands code syntax)

warpgrep Fast text/regex search (20x faster grep)

Use ast-grep when you need syntax-aware matching. Use warpgrep for raw speed.

MCP Server Required

Requires ast-grep server in mcp_config.json.