This project provides a Claude Code plugin that integrates ast-grep, enabling powerful, structure-aware code searching. It targets developers seeking to move beyond text-based code analysis, offering precise pattern matching for complex queries related to code quality, refactoring, security, and more. The primary benefit is enhanced code understanding and manipulation through Abstract Syntax Tree (AST) pattern matching, directly within the Claude Code environment.

How It Works

The plugin empowers Claude to interpret user requests for code patterns. It analyzes the query, generates corresponding ast-grep rules that understand code structure (AST), tests these rules against example code, and then executes them across the entire codebase. This AST-based approach allows for nuanced searches, such as finding specific function signatures, identifying code constructs within particular contexts, or detecting anti-patterns that text search would miss.

Quick Start & Requirements

• Primary Install: Add the marketplace via /plugin marketplace add ast-grep/claude-skill, then install the plugin using /plugin install ast-grep. A restart of Claude Code is required.
• Prerequisites: ast-grep CLI must be installed locally. Installation options include brew install ast-grep (macOS), npm install -g @ast-grep/cli, or cargo install ast-grep. Verify with ast-grep --version.
• Links:
  • ast-grep Official Documentation: https://ast-grep.github.io/
  • ast-grep Playground: https://ast-grep.github.io/playground/

Highlighted Details

• Structure-Aware Search: Matches code based on AST structure, not just text.
• Metavariables: Utilizes $VAR syntax to match any expression, statement, or identifier.
• Relational Queries: Enables finding code within specific contexts (e.g., "find X inside Y").
• Composite Logic: Supports combining rules with AND, OR, and NOT operations.
• Test-Driven Rules: Rules are automatically tested before execution against the codebase.
• Broad Language Support: Includes JavaScript/TypeScript, Python, Rust, Go, Java, C/C++, Ruby, PHP, and more.

Maintenance & Community

Contributions involve editing SKILL.md and adding examples to the references/ directory. For issues related to ast-grep itself, users are directed to the ast-grep GitHub repository. Specific community channels (like Discord or Slack) for this skill are not detailed in the README.

Licensing & Compatibility

The skill follows ast-grep's MIT license for included documentation and examples. This license generally permits commercial use and integration into closed-source projects, though specific interpretations may vary.

Limitations & Caveats

Claude Code does not automatically detect all scenarios where ast-grep would be beneficial; users must explicitly prompt Claude to use the skill. Debugging requires specific commands to ask Claude to reveal generated rules or AST structures.