> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AST-Grep Agent

> AST-based structural code search and rewrite tools for AI agents.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "AST-Grep Agent"
        Request[📋 User Request] --> Process[⚙️ AST-Grep Agent]
        Process --> Result[✅ Result]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Request input
    class Process process
    class Result output
```

<Note>
  **Prerequisites**

  * Python 3.10 or higher
  * PraisonAI Agents package installed
  * ast-grep CLI (`pip install ast-grep-cli` or `npm install -g @ast-grep/cli`)
</Note>

## AST-Grep Tools

Use AST-Grep Tools to search, analyze, and rewrite code using structural patterns instead of regex.

<Tip>
  Unlike regex, AST patterns understand code structure — they won't match patterns inside comments or strings. `$VAR` captures a single node, `$$$` captures multiple nodes.
</Tip>

<Steps>
  <Step title="Install Dependencies">
    Install PraisonAI Agents and ast-grep:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install praisonaiagents
    pip install ast-grep-cli
    ```
  </Step>

  <Step title="Import Components">
    Import the AST-grep tools:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent
    from praisonaiagents.tools import ast_grep_search, ast_grep_rewrite, ast_grep_scan
    ```
  </Step>

  <Step title="Create Agent">
    Create a code analysis agent:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    agent = Agent(
        name="CodeAnalyzer",
        instructions="Analyze and refactor code using AST patterns.",
        tools=[ast_grep_search, ast_grep_rewrite, ast_grep_scan],
    )
    ```
  </Step>

  <Step title="Run Agent">
    Start the agent:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    result = agent.start("Find all async function definitions in ./src")
    ```
  </Step>
</Steps>

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as AST-Grep Agent

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result
    Agent-->>User: Response
```

The user describes a refactor or search; the agent runs AST-grep search, rewrite, or scan tools on the codebase.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart LR
    subgraph Agent["Code Agent"]
        A[🤖 Agent]
    end

    subgraph Tools["AST-Grep Tools"]
        S[🔍 Search]
        R[✏️ Rewrite]
        SC[📋 Scan]
    end

    subgraph Code["Codebase"]
        F[Source Files]
    end

    A -->|"pattern + lang"| S
    A -->|"pattern + replacement"| R
    A -->|"rules YAML"| SC
    S --> F
    R --> F
    SC --> F

    style A fill:#8B0000,color:#fff
    style S fill:#189AB4,color:#fff
    style R fill:#189AB4,color:#fff
    style SC fill:#189AB4,color:#fff
    style F fill:#10B981,color:#fff
    classDef tool fill:#189AB4,color:#fff
    classDef agent fill:#8B0000,color:#fff
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent
    from praisonaiagents.tools import ast_grep_search

    agent = Agent(
        name="CodeSearcher",
        instructions="Search code for structural patterns.",
        tools=[ast_grep_search],
    )

    result = agent.start("Find all function definitions in ./src")
    ```
  </Step>

  <Step title="With Configuration">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent
    from praisonaiagents.tools import ast_grep_search, ast_grep_rewrite

    agent = Agent(
        name="Refactorer",
        instructions="Search and refactor code patterns.",
        tools=[ast_grep_search, ast_grep_rewrite],
    )

    result = agent.start("Rename all instances of \"old_function\" to \"new_function\" in Python files under ./src")
    ```
  </Step>
</Steps>

***

## Available Functions

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.tools import ast_grep_search
from praisonaiagents.tools import ast_grep_rewrite
from praisonaiagents.tools import ast_grep_scan
from praisonaiagents.tools import get_ast_grep_tools
from praisonaiagents.tools import is_ast_grep_available
```

## Function Details

### ast\_grep\_search(pattern, lang, path=".", json\_output=True)

Searches code using AST patterns. Returns structured JSON results.

| Parameter     | Type   | Default  | Description                                                                      |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------- |
| `pattern`     | `str`  | required | AST pattern (`$VAR` = single node, `$$$` = multiple)                             |
| `lang`        | `str`  | required | Language: `python`, `javascript`, `typescript`, `rust`, `go`, `java`, `c`, `cpp` |
| `path`        | `str`  | `"."`    | File or directory to search                                                      |
| `json_output` | `bool` | `True`   | Return JSON format                                                               |

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Find all Python function definitions
result = ast_grep_search("def $FN($$$)", lang="python", path="./src")

# Find all console.log calls in JavaScript
result = ast_grep_search("console.log($$$)", lang="javascript")

# Find all async functions
result = ast_grep_search("async def $FN($$$)", lang="python")

# Find all class definitions with inheritance
result = ast_grep_search("class $NAME($BASE):", lang="python")
```

### ast\_grep\_rewrite(pattern, replacement, lang, path=".", dry\_run=True)

Rewrites code matching an AST pattern. **Dry-run by default** (shows changes without modifying files).

| Parameter     | Type   | Default  | Description                                         |
| ------------- | ------ | -------- | --------------------------------------------------- |
| `pattern`     | `str`  | required | AST pattern to match                                |
| `replacement` | `str`  | required | Replacement pattern (can reference `$VAR` captures) |
| `lang`        | `str`  | required | Programming language                                |
| `path`        | `str`  | `"."`    | File or directory                                   |
| `dry_run`     | `bool` | `True`   | Preview only — set `False` to apply                 |

<Warning>
  Setting `dry_run=False` will modify files in place. Always preview first with the default `dry_run=True`.
</Warning>

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Preview: rename a function (dry run)
result = ast_grep_rewrite(
    "def old_name($$$)",
    "def new_name($$$)",
    lang="python",
    path="./src"
)

# Actually apply: replace console.log with logger.info
result = ast_grep_rewrite(
    "console.log($MSG)",
    "logger.info($MSG)",
    lang="javascript",
    dry_run=False
)
```

### ast\_grep\_scan(path=".", rule\_file=None)

Scans code using YAML-based lint rules.

| Parameter   | Type  | Default | Description                                             |
| ----------- | ----- | ------- | ------------------------------------------------------- |
| `path`      | `str` | `"."`   | File or directory to scan                               |
| `rule_file` | `str` | `None`  | Path to YAML rule file (uses `sgconfig.yml` if not set) |

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Scan with default rules
result = ast_grep_scan(path="./src")

# Scan with custom rules
result = ast_grep_scan(path="./src", rule_file="./rules/security.yml")
```

***

## Autonomy Mode

AST-grep tools are automatically included when using autonomy mode:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

# Tools auto-included via get_autonomy_default_tools()
agent = Agent(autonomy=True)
agent.start("Refactor the codebase to use consistent naming")
```

<Tip>
  In autonomy mode, ast-grep tools are available without explicit `tools=` — the agent can use them whenever it decides to search or rewrite code.
</Tip>

***

## Graceful Fallback

AST-grep tools work safely even when ast-grep is **not installed**:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.tools import is_ast_grep_available, ast_grep_search

# Check availability
if is_ast_grep_available():
    result = ast_grep_search("def $FN($$$)", lang="python")
else:
    print("ast-grep not installed")

# Or just call it — returns helpful install instructions
result = ast_grep_search("def $FN($$$)", lang="python")
# If not installed, returns:
# "ast-grep is not installed or not available in PATH.
#  To install: pip install ast-grep-cli"
```

<Info>
  Agents with ast-grep tools will **never crash** if ast-grep is missing. The tools return install instructions instead.
</Info>

***

## Pattern Syntax

| Pattern      | Meaning               | Example                                  |
| ------------ | --------------------- | ---------------------------------------- |
| `$VAR`       | Match single AST node | `def $FN()` matches any no-arg function  |
| `$$$`        | Match multiple nodes  | `def $FN($$$)` matches any function      |
| Literal code | Match exactly         | `print("hello")` matches that exact call |

### Pattern Examples by Language

<AccordionGroup>
  <Accordion title="Python">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # All function definitions
    "def $FN($$$)"

    # All class definitions
    "class $NAME($$$):"

    # All if statements
    "if $COND: $$$"

    # All async functions
    "async def $FN($$$)"

    # All list comprehensions
    "[$EXPR for $VAR in $ITER]"
    ```
  </Accordion>

  <Accordion title="JavaScript / TypeScript">
    ```javascript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    // All arrow functions
    "($$$) => $BODY"

    // All console.log calls
    "console.log($$$)"

    // All async functions
    "async function $FN($$$) { $$$ }"

    // All React useState hooks
    "const [$STATE, $SETTER] = useState($$$)"

    // All fetch calls
    "fetch($URL, $$$)"
    ```
  </Accordion>

  <Accordion title="Rust">
    ```rust theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    // All function definitions
    "fn $FN($$$) -> $RET { $$$ }"

    // All impl blocks
    "impl $TYPE { $$$ }"

    // All match expressions
    "match $EXPR { $$$ }"

    // All unsafe blocks
    "unsafe { $$$ }"
    ```
  </Accordion>
</AccordionGroup>

***

## Examples

<AccordionGroup>
  <Accordion title="Security Audit Agent">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, Task, AgentTeam
    from praisonaiagents.tools import ast_grep_search, ast_grep_scan

    security_agent = Agent(
        name="SecurityAuditor",
        instructions="""Audit code for security vulnerabilities:
        - Find eval() and exec() calls
        - Find SQL string concatenation
        - Find hardcoded credentials""",
        tools=[ast_grep_search, ast_grep_scan],
    )

    audit_task = Task(
        description="Audit ./src for security issues: eval/exec usage, SQL injection, hardcoded secrets.",
        expected_output="Security report with findings and recommendations.",
        agent=security_agent,
        name="security_audit"
    )

    team = AgentTeam(agents=[security_agent], tasks=[audit_task], process="sequential")
    team.start()
    ```
  </Accordion>

  <Accordion title="Code Migration Agent">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent
    from praisonaiagents.tools import ast_grep_search, ast_grep_rewrite

    migrator = Agent(
        name="Migrator",
        instructions="""Migrate code patterns:
        - Replace deprecated APIs with new ones
        - Always preview first (dry_run=True)
        - Only apply changes after confirming the preview""",
        tools=[ast_grep_search, ast_grep_rewrite],
    )

    result = migrator.start(
        "Replace all console.log calls with logger.info in JavaScript files under ./app"
    )
    ```
  </Accordion>

  <Accordion title="Multi-Agent Code Review">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, Task, AgentTeam
    from praisonaiagents.tools import ast_grep_search, ast_grep_scan

    # Searcher finds patterns
    searcher = Agent(
        name="PatternFinder",
        instructions="Find code patterns and anti-patterns using AST search.",
        tools=[ast_grep_search],
    )

    # Reviewer analyzes findings
    reviewer = Agent(
        name="CodeReviewer",
        instructions="Review code quality findings and provide recommendations.",
    )

    search_task = Task(
        description="Find all functions longer than 50 lines and deeply nested conditionals.",
        agent=searcher,
        name="pattern_search"
    )

    review_task = Task(
        description="Review the search findings and provide refactoring recommendations.",
        agent=reviewer,
        name="code_review"
    )

    team = AgentTeam(
        agents=[searcher, reviewer],
        tasks=[search_task, review_task],
        process="sequential"
    )
    team.start()
    ```
  </Accordion>
</AccordionGroup>

***

## Dependencies

| Package           | Required | Install                                                      |
| ----------------- | -------- | ------------------------------------------------------------ |
| `praisonaiagents` | Yes      | `pip install praisonaiagents`                                |
| `ast-grep-cli`    | Optional | `pip install ast-grep-cli` or `npm install -g @ast-grep/cli` |

<Info>
  Install the optional autonomy extras for ast-grep + other autonomy tools:

  ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  pip install praisonaiagents[autonomy]
  ```
</Info>

## Error Handling

All functions include comprehensive error handling:

* **Not installed**: Returns helpful install instructions
* **Empty pattern**: Returns clear error message
* **Timeout**: 60s for search, 120s for rewrite/scan
* **Subprocess errors**: Captured and returned as strings
* **No matches**: Returns "No matches found" (not an error)

## Related

<CardGroup cols={2}>
  <Card title="Shell Tools" icon="terminal" href="/docs/tools/shell_tools">
    Execute shell commands
  </Card>

  <Card title="Python Tools" icon="python" href="/docs/tools/python_tools">
    Execute Python code
  </Card>

  <Card title="File Tools" icon="file" href="/docs/tools/file_tools">
    File system operations
  </Card>

  <Card title="Security" icon="shield-halved" href="/docs/best-practices/security">
    Security best practices
  </Card>
</CardGroup>