What is ast-grep-find?

An AST-aware search and refactor tool that uses ast-grep MCP to match code syntax rather than raw text.

How do I enable the MCP server?

Ensure an ast-grep server is configured via mcp_config.json and running in your environment.

What do the pattern tokens mean?

Pattern syntax uses $NAME to match a single node, $$$ to match multiple nodes, and $_ as a wildcard, enabling robust AST queries.

ast-grep-find

npx machina-cli add skill parcadei/Continuous-Claude-v3/ast-grep-find --openclaw

Files (1)

SKILL.md

2.6 KB

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.

Source

git clone https://github.com/parcadei/Continuous-Claude-v3/blob/main/.claude/skills/ast-grep-find/SKILL.mdView on GitHub

Overview

AST-Grep Find enables syntax-aware code search by matching AST patterns rather than raw text. It can locate patterns like function calls, imports, and class definitions, and supports refactoring with AST precision across languages via the ast-grep MCP server.

How This Skill Works

Run the harness with a --pattern and --language to search code. The tool uses AST pattern syntax ($NAME, $$$, $_) to find matches, and can perform replacements with --replace when you’re ready. Queries run against a configured AST backend (MCP) to ensure syntax-aware results.

When to Use It

Find code patterns (ignores strings/comments)
Search for function calls, class definitions, and imports
Refactor code with AST precision
Rename variables or functions across a codebase
Dry-run previews of changes before applying refactors

Quick Start

Step 1: Run a search with --pattern and --language
Step 2: Narrow scope with --path and optional --glob
Step 3: Apply a replacement with --replace or preview with --dry-run

Best Practices

Always start with --dry-run to preview changes
Narrow searches with --path or --glob
Specify --language for accurate parsing
Use the pattern syntax tokens ($NAME, $$$, $_) to build robust matches
Validate refactors with tests and incremental passes

Example Use Cases

Find all Python function definitions: def $FUNC($$$):
Find console.log calls in JavaScript
Replace print with logging in Python (dry-run)
Search for imports like import asyncio across a repo
Rename a variable across modules using a single pattern

Frequently Asked Questions

Add this skill to your agents