> ## 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.

# Search Tools

> Fast, capped grep and glob built-ins for code-searching agents

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

agent = Agent(
    name="Code Search",
    instructions="Find symbols and files in the repository.",
    tools=[grep, glob],
)
agent.start("Find all TODO comments under src/")
```

The user describes what to locate in the codebase; the agent runs grep and glob with safe caps.

Give your agent two zero-config primitives — `grep` to find text, `glob` to find files — bounded, path-safe, and ripgrep-accelerated when available.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Search Tools"
        A[🤖 Agent] --> B[grep / glob]
        B --> C{rg on PATH?}
        C -->|Yes| D[⚡ ripgrep]
        C -->|No| E[🐍 Python fallback]
        D --> F[✅ Capped result]
        E --> F
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class A agent
    class B tool
    class C decision
    class D,E tool
    class F result
```

## Quick Start

**1. Agent-Centric Usage**

Attach `grep` and `glob` to an agent — no configuration needed.

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

agent = Agent(
    name="Coder",
    instructions="Find and explore code in this repo.",
    tools=[grep, glob],
)

agent.start("Where is `deprecated_fn` used?")
```

**2. Direct Usage**

Call both tools directly outside an agent.

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

print(grep("deprecated_fn", path="src", glob="*.py"))
print(glob("**/*.py", path="src"))
```

**Python**

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

agent = Agent(
    name="Coder",
    instructions="Find and explore code in this repo.",
    tools=[grep, glob],
)

agent.start("List all Python files in src and find TODO comments")
```

**YAML**

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agents:
  - name: coder
    instructions: Find and explore code.
    tools:
      - grep
      - glob
```

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant grep/glob
    participant Backend

    User->>Agent: "Find all TODO comments in src/"
    Agent->>grep/glob: grep("TODO", path="src", glob="*.py")
    grep/glob->>Backend: ripgrep (if available) or Python walker
    Backend-->>grep/glob: raw matches
    grep/glob-->>Agent: capped result (path:line: text)
    Agent-->>User: "Found 42 TODOs — here are the top 100..."
```

| Backend | When used | Notes |
| - | - | - |
| `ripgrep` (`rg`) | Auto-detected on `PATH` | Faster; linear-time RE2 engine; 30s timeout |
| Pure-Python | Fallback | Zero deps; regex pattern length capped at 1000 chars |

***

## Configuration Options

### `grep` Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `pattern` | `str` | *(required)* | Regex or literal string to search for |
| `path` | `str` | `"."` | Directory or single file to search under |
| `glob` | `str` | `None` | Filename glob to restrict the search (e.g. `"*.py"`) |
| `case_insensitive` | `bool` | `False` | Case-insensitive matching when `True` |
| `max_results` | `int` | `100` | Hard cap on matching lines returned; invalid/≤0 snaps back to 100 |

**Returns:** `path:line: matched line` entries (newline-joined), hard-capped with a truncation hint. Returns `"No matches found."` or `"Error: …"` on error.

### `glob` Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `pattern` | `str` | *(required)* | Glob pattern (e.g. `"**/*.ts"`, `"src/**/test_*.py"`) |
| `path` | `str` | `"."` | Directory to search under |
| `max_results` | `int` | `100` | Hard cap on paths returned; invalid/≤0 snaps back to 100 |

**Returns:** Newline-joined workspace-relative file paths, sorted by modification time (newest first), hard-capped with a truncation hint. Returns `"No files found."` on empty results.

***

## Common Patterns

**Case-insensitive search across `.py` files only:**

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

result = grep("TODO", glob="*.py", case_insensitive=True)
print(result)
```

**Recursive TypeScript file listing:**

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

files = glob("**/*.ts", path="src")
print(files)
```

**Bounded search in a large repo:**

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

result = grep("error", max_results=50)
print(result)
```

***

## Choosing Between `grep`, `glob`, and AST-Grep

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q{What do you need?} --> A[Find text/regex\ninside files]
    Q --> B[Find files\nby name pattern]
    Q --> C[Find or rewrite code\nby structure]

    A --> grep[grep]
    B --> glob[glob]
    C --> ast[ast_grep_search\nast_grep_rewrite]

    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef ast fill:#6366F1,stroke:#7C90A0,color:#fff

    class Q decision
    class grep,glob tool
    class ast ast
```

***

## Best Practices

> **Install ripgrep for speed (optional)**
>
> `ripgrep` is an optional accelerator — the tools always work without it. Install for significantly faster searches on large codebases.
>
> ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> # macOS
> brew install ripgrep
>
> # Ubuntu/Debian
> apt install ripgrep
>
> # Windows
> choco install ripgrep
> ```

> **Narrow with glob and path early**
>
> Both tools default to a cap of 100 results. Use `glob` and `path` to narrow the search before hitting the limit.
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents.tools import grep
>
> # Narrow: search only Python files under src/
> result = grep("authenticate", path="src", glob="*.py")
> ```

> **Read the truncation hint**
>
> When results are capped, the last line contains a truncation hint like:
>
> ```
> ... 100+ matches (truncated at 100); refine the pattern or narrow `path`/`glob`.
> ```
>
> Agents can detect this string and automatically refine their query.

> **Trust .gitignore — it's already honoured**
>
> Both tools automatically respect `.gitignore` (including negation patterns like `!keep.log` and directory-only rules like `build/`). Noise directories like `.git`, `node_modules`, `__pycache__`, and `.venv` are always skipped.

***

## User Interaction Flow

A typical agent conversation using `grep` and `glob`:

```
User:  "Find all TODO comments in the src/ directory"

Agent: calls grep("TODO", path="src", case_insensitive=True)
       → "src/auth.py:42: # TODO: add rate limiting
          src/api.py:87: # TODO: handle edge case
          ... 100+ matches (truncated at 100); refine the pattern or narrow `path`/`glob`."

User:  "Too many — only show the ones in auth files"

Agent: calls grep("TODO", path="src", glob="*auth*")
       → "src/auth.py:42: # TODO: add rate limiting
          src/auth_middleware.py:15: # TODO: validate tokens"

User:  "Which Python files exist in that folder?"

Agent: calls glob("**/*.py", path="src")
       → "src/auth.py
          src/auth_middleware.py
          src/api.py
          ..."
```

***

## Related

> **[AST-Grep Tools](https://praison.ai/docs/tools/ast-grep-tools.md)**
>
> Structural code search and rewrite using AST patterns

> **[File Tools](https://praison.ai/docs/tools/file_tools.md)**
>
> File system operations and management utilities


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.