Code Search (Grep)

Relevant source files

The following files were used as context for generating this wiki page:

• vibe/core/tools/builtins/grep.py
• vibe/cli/textual_ui/widgets/tool_widgets.py
• vibe/core/tools/builtins/prompts/bash.md
• vibe/core/prompts/plan_mode.md
• CLAUDE.md
• README.md

The Code Search system in QQcode provides a robust, recursive regex searching capability designed to explore local codebases. It serves as a primary tool for the AI agent to locate specific implementations, TODOs, or patterns within a project without needing to read every file individually. The system is designed to be efficient by wrapping high-performance CLI tools like ripgrep (rg) while falling back to standard grep when necessary.

Sources: vibe/core/tools/builtins/grep.py:100-103, README.md:68-69

Core Architecture

The Grep tool is implemented as a builtin tool within the vibe.core.tools ecosystem. It follows a structured execution flow that includes backend detection, argument validation, pattern collection for exclusions, and asynchronous command execution.

Backend Detection and Selection

The tool dynamically detects the best available search engine on the host system. It prioritizes ripgrep due to its performance and native support for ignore files, falling back to GNU grep if ripgrep is missing. If neither is found, the tool raises a ToolError.

Execution Logic

The execution process is handled asynchronously. The tool collects exclusion patterns from three sources: hardcoded defaults, user configuration, and a .qqcodeignore file.

1. Validation: Ensures the search pattern is not empty and the target path exists.
2. Pattern Collection: Merges default exclusions (e.g., .venv, node_modules, .git) with custom patterns.
3. Command Building: Constructs the specific CLI flags required for the chosen backend.
4. Output Parsing: Captures stdout, enforces match limits, and handles truncation if the output exceeds byte limits.

Sources: vibe/core/tools/builtins/grep.py:115-125, vibe/core/tools/builtins/grep.py:161-177

Data Models and Configuration

The tool utilizes Pydantic models to define its configuration, input arguments, and resulting output structure.

Configuration Options

Option	Type	Default	Description
permission	ToolPermission	ALWAYS	Execution permission level.
max_output_bytes	int	64,000	Hard cap on total size of matched lines returned.
default_max_matches	int	100	Default limit for the number of matches.
exclude_patterns	list[str]	[Various]	Default paths to ignore (e.g., .git/, dist/).
codeignore_file	str	.qqcodeignore	Filename for additional project-specific ignores.

Sources: vibe/core/tools/builtins/grep.py:35-81

Tool Arguments (GrepArgs)

Parameter	Type	Required	Description
pattern	str	Yes	The regex pattern to search for.
path	str	No (.)	Target directory to search.
max_matches	int	No	Override for the maximum number of matches.
use_default_ignore	bool	No (True)	Whether to respect .gitignore and .ignore.

Sources: vibe/core/tools/builtins/grep.py:89-98

User Interface and Display

QQcode provides specific Textual widgets to handle the visualization of search results in the CLI TUI.

Result Visualization

The GrepResultWidget manages how matches are presented to the user. It supports a "collapsed" view that shows a summary (e.g., "Found 5 matches") and an "expanded" view that displays the actual code snippets with syntax highlighting via Markdown.

Status and Truncation

The UI provides explicit feedback when results are truncated due to limits.

• Match Truncation: If the search finds more matches than max_matches, the UI appends "(truncated)".
• Byte Truncation: If matches exceed max_output_bytes, the output is sliced to prevent context window overflow in the LLM.

Sources: vibe/core/tools/builtins/grep.py:214-230, vibe/cli/textual_ui/widgets/tool_widgets.py:301-305

Usage Constraints and Guidelines

The project includes strict guidelines on when to use the dedicated grep tool versus standard bash commands.

Prohibited Bash Commands

The following bash operations are discouraged in favor of the grep tool:

• grep -r "pattern" .
• find . -name "*.py"
• ag, ack, or rg directly via shell.

Sources: vibe/core/tools/builtins/prompts/bash.md:15-19

Plan Mode Integration

In "Plan Mode", the grep tool remains available as a read-only exploration tool. This allows the agent to analyze the codebase and locate relevant files before proposing any modifications via a implementation plan.

Sources: vibe/core/prompts/plan_mode.md:7-10

Implementation Snippet

The following snippet illustrates how the tool constructs the ripgrep command with smart-case and ignore handling:

# vibe/core/tools/builtins/grep.py:179-198
def _build_ripgrep_command(
    self, args: GrepArgs, exclude_patterns: list[str]
) -> list[str]:
    max_matches = args.max_matches or self.config.default_max_matches
    cmd = [
        "rg",
        "--line-number",
        "--no-heading",
        "--smart-case",
        "--no-binary",
        "--max-count",
        str(max_matches + 1),
    ]
    if not args.use_default_ignore:
        cmd.append("--no-ignore")
    for pattern in exclude_patterns:
        cmd.extend(["--glob", f"!{pattern}"])
    cmd.extend(["-e", args.pattern, args.path])
    return cmd

Sources: vibe/core/tools/builtins/grep.py:179-198

Summary

The Code Search (Grep) system is a critical component for codebase navigation in QQcode. By abstracting high-performance search tools behind a standardized interface, it provides the agent with the ability to perform high-speed, recursive searches while respecting project configurations like .gitignore and .qqcodeignore. The integration with the Textual-based UI ensures that users can interactively browse search results with proper truncation handling and syntax-aware rendering.