ast-grep

Identify code structures across TypeScript and Python using AST patterns.

Updated May 13, 2026
One-click install
npx skills add https://github.com/usetheodev/theo-ui --skill ast-grep-usetheodev
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: ast-grep
Source: https://github.com/usetheodev/theo-ui/tree/main/.claude/skills/ast-grep
Command: npx skills add https://github.com/usetheodev/theo-ui --skill ast-grep-usetheodev

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

AST-based code discovery and refactoring across multi-language codebases to identify shapes and patterns rather than textual matches.

Core Features & Use Cases

  • Structural search using tree-sitter patterns to map where specific code shapes exist (e.g., classes, functions, decorators) across languages.
  • Two-phase investigation workflow: zoom out to map hotspots and zoom in for deep reads, enabling efficient cross-language analysis.
  • Composable and scriptable: can be consumed by other skills or invoked directly from any context (code review, debugging, refactor planning).

Quick Start

Run ast-grep scan with a YAML rule file against a codebase to map hotspots by AST shape.

Frequently Asked Questions about ast-grep

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

FAQPage Schema
How do I find class hierarchies and function signatures across multi-language codebases?

Structural code search identifies class hierarchies and function signatures across multi-language codebases using AST patterns. It parses code shapes with tree-sitter to map exact structural locations rather than relying on textual matches.

What is the best way to map code hotspots before planning a cross-language refactor?

Mapping code hotspots before a cross-language refactor is best done using a two-phase investigation workflow. You zoom out to map structural hotspots with AST patterns, then zoom in for deep reads to analyze the specific code shapes.

How do I run a structural search to find decorators and call sites in TypeScript and Python?

To run a structural search for decorators and call sites in TypeScript and Python, you execute a scan with a YAML rule file. This drives the tree-sitter-based parsing to identify matching code structures across the project.

Does structural code search work with rule files for automated code analysis?

Yes, structural code search works with rule files for automated code analysis by accepting YAML rule files under the rules directory. These rules drive the AST pattern matching to find specific code shapes during discovery workflows.

Can I use AST pattern matching for code review and debugging instead of just refactoring?

You can use AST pattern matching for code review and debugging because the structural search is composable and scriptable. It can be invoked directly from any context to identify code shapes, making it suitable for review workflows.

Why use tree-sitter based parsing instead of textual search for code discovery?

Tree-sitter based parsing is used instead of textual search for code discovery because it identifies structural code shapes rather than string matches. This prevents false positives when mapping class hierarchies, decorators, and function signatures.