Skip to main content
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.

​
Quick Start

1

Agent-Centric Usage

Attach grep and glob to an agent — no configuration needed.
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.
from praisonaiagents.tools import grep, glob

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

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")

​
How It Works

BackendWhen usedNotes
ripgrep (rg)Auto-detected on PATHFaster; linear-time RE2 engine; 30s timeout
Pure-PythonFallbackZero deps; regex pattern length capped at 1000 chars

​
Configuration Options

​
grep Parameters

ParameterTypeDefaultDescription
patternstr(required)Regex or literal string to search for
pathstr"."Directory or single file to search under
globstrNoneFilename glob to restrict the search (e.g. "*.py")
case_insensitiveboolFalseCase-insensitive matching when True
max_resultsint100Hard 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

ParameterTypeDefaultDescription
patternstr(required)Glob pattern (e.g. "**/*.ts", "src/**/test_*.py")
pathstr"."Directory to search under
max_resultsint100Hard 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: 
from praisonaiagents.tools import grep

result = grep("TODO", glob="*.py", case_insensitive=True)
print(result)
Recursive TypeScript file listing: 
from praisonaiagents.tools import glob

files = glob("**/*.ts", path="src")
print(files)
Bounded search in a large repo: 
from praisonaiagents.tools import grep

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

​
Choosing Between grep, glob, and AST-Grep

​
Best Practices

ripgrep is an optional accelerator — the tools always work without it. Install for significantly faster searches on large codebases.
# macOS
brew install ripgrep

# Ubuntu/Debian
apt install ripgrep

# Windows
choco install ripgrep
Both tools default to a cap of 100 results. Use glob and path to narrow the search before hitting the limit.
from praisonaiagents.tools import grep

# Narrow: search only Python files under src/
result = grep("authenticate", path="src", glob="*.py")
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.
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
          ..."

AST-Grep Tools

Structural code search and rewrite using AST patterns

File Tools

File system operations and management utilities