Workspace Search

Honor explicit tool choices, repository conventions, and access boundaries. Discover available tools once per working environment and consult relevant CLI help as needed.

Search decision tree

1. Searching for calls, declarations, imports, or other code syntax patterns? Prefer ast-grep when the language and pattern are supported. For file paths, exact strings, comments, logs, or configuration keys, use text search. When ast-grep is unavailable or unsuitable, text matches are candidates requiring context checks.
2. Reuse or scan? For text search, reuse a ready tgrep service covering the intended scope; otherwise use direct scanning: choose the first available, suitable tool in rg → tgrep --no-index → grep order. Read Indexed search before relying on or preparing an index.
3. Upgrade to an index? If direct scanning is slow and more queries are expected, or substantial repeated searches across a large workspace are predictable, prepare tgrep indexing and serving within authorized scope. Once ready, use it for subsequent queries. Small scopes and one-off queries stay on direct scanning; tool availability alone does not justify indexing.

Use the same direct-scanning order when an index is unreliable, a service fails, or an indexed result needs verification. Preserve equivalent scope and filters. If no suitable tool is available, report the limitation rather than silently installing one.

Execute efficiently

Start with the requested root and likely owning paths; use the selected tool's file-discovery mode when location is unknown. Choose filenames, bounded context, or structured output according to the next decision. Narrow or partition truncated output rather than treating a displayed sample as complete.

For a simple code syntax pattern, select the language, search directly, and inspect the matches. For complex patterns, unexpected empty results, or excessive noise, check a representative match and non-match before expanding the search. Preserve the intended scope and filters when using an index.

If a tool fails, correct a clear invocation error using its help. If the failure persists or the tool cannot express the query, switch to a suitable fallback and continue the search; report any resulting limitation. Clean up any task-owned startup process after service preparation fails. Investigate the tool itself only when that is part of the requested task.