ast-grep

Find code patterns by matching Abstract Syntax Tree structures via ast-grep CLI.

Updated Dec 18, 2025
One-click install
npx skills add https://github.com/convective/cpg-elf-portal --skill ast-grep-convective
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: ast-grep
Source: https://github.com/convective/cpg-elf-portal/tree/main/.claude/skills/ast-grep
Command: npx skills add https://github.com/convective/cpg-elf-portal --skill ast-grep-convective

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill enables searching code by Abstract Syntax Tree (AST) patterns rather than raw text, allowing detection of bug patterns and refactoring candidates that are dependent on syntax rather than formatting or naming.

Core Features & Use Cases

  • Structural search: Find code patterns based on syntax (AST), not on textual formatting.
  • Bug pattern detection: Identify structural bugs across languages.
  • Refactoring & auditing: Spot refactoring opportunities by pattern.
  • Use Case: Locate all occurrences of a specific subtraction pattern like discount - $VAR in TypeScript to surface incorrect operand ordering.

Quick Start

Run: ast-grep run -p 'PATTERN' -l LANGUAGE to search for AST patterns, e.g., ast-grep run -p 'discount - $VAR' -l typescript

Frequently Asked Questions about ast-grep

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find code patterns across a codebase without searching by text?

Structural code search uses Abstract Syntax Tree (AST) pattern matching to locate code by syntax structure rather than text formatting. Run ast-grep with a pattern like `ast-grep run -p 'discount - $VAR' -l typescript` to find matches regardless of variable names or whitespace, returning exact structural matches.

Can I detect bug patterns across multiple programming languages at once?

Yes. AST-based pattern matching detects bug patterns consistently across languages by matching syntax structure, not text. Specify the language with the -l flag (e.g., typescript, python, java) to search for the same structural bug pattern in codebases written in different languages.

What's the best way to identify refactoring opportunities in legacy code?

AST pattern matching identifies refactoring candidates by finding structural patterns that indicate code smells or deprecated usage. Use ast-grep to define patterns matching the syntax you want to replace, then locate all occurrences across your codebase for bulk refactoring.

How do I spot incorrect operand ordering or similar subtle syntax bugs?

Define AST patterns that capture the problematic syntax structure. For example, search for `discount - $VAR` to surface cases where operand order matters. The pattern syntax uses tokens like $VAR and $$$ to match variable positions and statement sequences, catching bugs that text search would miss.

Can I use AST pattern matching to audit API usage across my codebase?

Yes. Define patterns matching the API calls or usage structures you want to track, then run ast-grep to find all occurrences. This is useful for API deprecation audits, security reviews, or enforcing consistent usage patterns across teams.

Does AST pattern matching require preprocessing or special file format setup?

No special setup is needed. ast-grep runs directly on source code files via the CLI. Provide the pattern, specify the language, and it parses the code into AST structures on the fly, returning matches without requiring intermediate transformations or format conversion.