Ripgrep Over Grep Command

Structured Native Code Search Protocol (grep_search over Shell grep)

Overview

When searching a codebase for a function, type, or error string ("Where is validateJwtSession defined?"), naive agents execute terminal shell commands (run_command("grep -rn 'validateJwtSession' .")).

Spawning terminal shell grep commands introduces three major inefficiencies:

1. ANSI Formatting & Paging Pollution: Terminal output includes ANSI terminal escape codes, unstructured whitespace wrapping, and pager formatting that clutters the conversation context.
2. Match Flood Overflows: Shell grep has no built-in result cap. If a term matches 2,000 lines across build files, it dumps 50,000+ tokens into context in one shot.
3. Subprocess Spawn Latency: Initializing a shell subprocess takes 400ms+, whereas native IDE search tools execute in 5 milliseconds.

The Structured Native Code Search Protocol enforces the use of the native grep_search tool - returning clean, structured JSON with strict match ceilings and glob filtering.

Shell Subprocess grep -rn vs. Native grep_search Tool

┌─────────────────────────────────────────────────────────────┐
│                 Code Search Output Comparison               │
│                                                             │
│  Shell Subprocess `grep -rn` (145 Tokens / 520ms):          │
│  ./src/services/auth.ts:42:export function validateJwtSession│
│  ./src/services/auth.ts:98:  const res = validateJwtSession │
│  ./tests/auth.test.ts:14:    const valid = validateJwtSession│
│  ↳ Unstructured text, requires fragile regex to parse       │
│                                                             │
│  Native `grep_search` Tool (38 Tokens / 8ms - 73.8% Cut!):  │
│  [{"Filename":"src/services/auth.ts","LineNumber":42,       │
│    "LineContent":"export function validateJwtSession"}]     │
│  ↳ 38 clean tokens, instant clickable links, exact LineNumber│
└─────────────────────────────────────────────────────────────┘

The 4 Built-In Protections of grep_search

┌───────────────────────────────────────────────────────────────────────────┐
│ 1. AUTOMATIC MATCH CEILING: Hard-capped at 50 matches (Zero token flood)  │
│ 2. STRUCTURED JSON SCHEMA: Returns `Filename`, `LineNumber`, `LineContent`│
│ 3. INTEGRATED GLOB FILTERING: `Includes: ["src/**", "!**/*.test.ts"]`    │
│ 4. GITIGNORE-AWARE ENGINE: Rust-based ripgrep skips `node_modules` & `git`│
└───────────────────────────────────────────────────────────────────────────┘

Tool Invocation Standard

When searching for code symbols in Antigravity IDE / Claude Code:

{
  "Query": "validateJwtSession",
  "SearchPath": "c:/Users/ASUS/Documents/Newfolder/Antigravity/Major AI Skills",
  "CaseInsensitive": false,
  "IsRegex": false,
  "MatchPerLine": true,
  "Includes": ["src/**", "!**/dist/**", "!**/*.spec.ts"],
  "toolAction": "Searching for JWT session validator",
  "toolSummary": "Code Symbol Search"
}

Benchmark Comparison

Searching for a common utility function across a 2,500-file full-stack codebase:

Agent Operational Directive

MANDATORY: Agents must NEVER execute grep, findstr, or ack via shell execution tools (run_command). Always call the dedicated native grep_search tool for locating symbols, functions, and string patterns.