Ripgrep Plugin

The Ripgrep Plugin provides a ripgrep tool that allows agents to search for patterns in files using ripgrep, replacing the need for shell commands like find and grep.

Overview

The Ripgrep plugin:

1. Registers a ripgrep tool for pattern searching across files
2. Supports regex patterns, file type filtering, and case-sensitive/insensitive search
3. Makes the tool available to both main agents and subagents
4. Validates ripgrep availability at startup (logs error and skips registration if not found)

Requirements

ripgrep must be installed and available in PATH:

• Install from: https://github.com/BurntSushi/ripgrep
• Verify installation: rg --version
• The plugin will log an error and skip registration if ripgrep is not found

Configuration

Basic Configuration

plugins:
  - module: codumentor.plugins.ripgrep
    class: RipgrepPlugin
    args:
      enabled: true
      max_results: 1000          # Maximum results per search (default: 1000)
      max_result_length: 30000    # Maximum result content length in bytes (default: 30000)

Configuration Parameters

• enabled (optional): Whether the plugin is enabled (default: true)
• max_results (optional): Maximum number of results per search (default: 1000, max: 10000)
• max_result_length (optional): Maximum length of result content in bytes before truncation (default: 30000)

Tool Usage

The ripgrep tool provides the following parameters:

• pattern (required): Search pattern (regex by default, or literal text)
• Example: class.*DPMPortfolioZarasIgenyResponse searches for lines containing 'class' followed by any characters and then 'DPMPortfolioZarasIgenyResponse'

• search_dir (optional): Directory to search in, relative to the repos directory. Use "." or omit for searching all repos. Default: "."
• Format: "repo_name" or "repo_name/subdir"

• file_types (optional): File type filter (e.g., ".py", ".md", ".js" or [".py", "*.md"])

• files_only (optional): If true, return only file paths that contain matches (equivalent to grep -l). If false, return matching lines with context. Default: false

• case_sensitive (optional): If false, perform case-insensitive search. If true, search is case-sensitive. Default: true

• max_results (optional): Maximum number of results to return. Overrides plugin default. Range: 1-10000, default: 1000

Examples

Example 1: Search for a class definition

The agent can use the tool to find class definitions:

ripgrep(pattern="class.*DPMPortfolioZarasIgenyResponse", search_dir="my_repo", file_types="*.py")

Example 2: Find files containing a pattern

To find which files contain a pattern without showing the actual lines:

ripgrep(pattern="TODO", files_only=true)

Example 3: Case-insensitive search across all repos

ripgrep(pattern="api_key", case_sensitive=false)

Example 4: Search specific file types

ripgrep(pattern="function.*async", file_types=["*.js", "*.ts"])

How It Works

Tool Registration

The plugin registers the ripgrep tool via the onPromptAssemble hook:

• Called before each LLM prompt is assembled
• Adds the ripgrep tool to the available tools list
• Registers the tool with the agent's tool registry
• Works for both main agents and subagents

Availability Check

At registration time, the plugin:

1. Creates a RipgrepTool instance
2. Checks if ripgrep (rg) is available in PATH
3. If not available: logs an error and does not register the hook (tool will not be available)
4. If available: registers the hook normally

Search Execution

When the agent calls the ripgrep tool:

1. Validates ripgrep is available (returns error if not)
2. Builds ripgrep command with appropriate flags
3. Executes search in the specified directory (safely scoped to repos directory)
4. Formats results with metadata (pattern, directory, file types, etc.)
5. Truncates output if it exceeds max_result_length

Error Handling

The plugin handles various error scenarios:

• ripgrep not found: Plugin logs error and skips registration (tool not available)
• Invalid search directory: Tool returns error for paths outside repos directory
• Timeout: Search operations timeout after 30 seconds
• Encoding issues: Invalid UTF-8 characters are replaced instead of failing
• Output truncation: Large results are truncated with a message indicating the truncation

Security

• Path validation: Search directories are validated to ensure they're within the repos directory
• Subprocess execution: ripgrep runs with 30-second timeout
• Resource limits: Result size and count limits prevent excessive resource usage

Troubleshooting

Tool Not Available

If the ripgrep tool doesn't appear:

1. Check ripgrep installation: Run rg --version to verify ripgrep is in PATH
2. Check plugin logs: Look for error messages about ripgrep not being found
3. Verify configuration: Ensure the plugin is enabled in your config

Search Returns No Results

1. Check pattern: Verify the regex pattern is correct
2. Check directory: Ensure search_dir is correct relative to repos directory
3. Check file types: Verify file type filter matches your files
4. Case sensitivity: Try case_sensitive: false if unsure about casing

Performance Issues

1. Limit results: Use max_results to limit result count
2. Filter file types: Use file_types to narrow search scope
3. Use files_only: Set files_only: true if you only need file paths

Testing

The plugin includes comprehensive unit tests. Run tests with:

python -m unittest tests.test_ripgrep_plugin -v