Grep Search Tool Protocol

This skill documents known bugs and mandatory workarounds for the AI's internal grep_search tool. Because grep_search is used universally to search codebases, logs, and files, these rules apply globally.

CRITICAL ENVIRONMENT DIFFERENCES: IDE vs CLI

This skill file is shared between the Antigravity IDE and the Antigravity 2.0 CLI environments via a directory symlink. Because of backend software differences, the grep_search tool behaves entirely differently depending on which environment you are currently running in.

Before executing a search, you must check your environment by verifying if the ANTIGRAVITY_EDITOR_APP_ROOT environment variable is set (e.g. via run_command):

1. If the variable is ABSENT: You are in the 2.0 CLI. The tool is permanently dead on Windows and will crash. Workaround: You MUST abandon the grep_search tool entirely and use PowerShell's Select-String via the run_command tool instead.
2. If the variable is SET: You are in the IDE. Your tool works, but you are vulnerable to the wrapper bugs below and MUST follow their workarounds.

CRITICAL BUG: Single File Target Failure

The Bug: If you set the SearchPath argument of the grep_search tool to a direct, specific file path (e.g., C:\path\to\file.txt), the tool will silently fail and return No results found, even if the string exists in the file.

The Workaround: You MUST NEVER point SearchPath at a specific file. To search within a specific file, you must:

1. Set SearchPath to the parent directory containing the file (e.g., C:\path\to\).
2. Use the Includes array argument to filter for the exact filename (e.g., Includes: ["file.txt"]).

CRITICAL BUG: Minified JSON / Long Lines

The Bug: grep_search is a line-based text parser. If it is pointed at a file that contains extremely long lines (like a minified .json database or a single-line dump), the underlying grep engine will often silently truncate the output or drop the buffer, resulting in false negatives.

The Workaround: Do not use grep_search to find data inside large JSON databases or minified files. Instead, use a native script (like python -c "import json..." or powershell ConvertFrom-Json) to load and parse the object natively.