Skip to main content
The Engine ships several built-in file-search tools — grep, find, and a higher-level file_search that combines pattern matching with semantic relevance ranking. Together they give the agent the ability to work in a codebase or document collection it didn’t author.

​
What’s available

The agent picks among them based on what it knows.

​
Allowed paths

All file tools respect ALLOWED_ROOTS. The agent can search and read within the configured roots; everything else is invisible. There is no “how do I escape this” — landlock enforces the boundary at the kernel.

​
Patterns

​
grep before read_file

When the agent is hunting for a symbol:
This is two cheap calls instead of one expensive (read every file) call.

​
find before grep

When the agent doesn’t know which directory to search:

​
file_search for fuzzy intent

When the user’s question is conceptual (“where do we handle rate limits?”) and there’s no obvious string to grep for:
file_search uses the same hybrid scoring as memory search — vector similarity + keyword. Useful for codebases, documentation, content libraries.

​
Output limits

Tools cap output to keep context tidy:
  • grep truncates at ~100 matches by default. Tighten the pattern if you want more.
  • read_file caps at ~50 KB. Larger files are paginated; the agent asks for next pages.
  • file_search returns the top 10–20 results with snippets, not full files.

​
Pitfalls

  • Searching the world. A grep -r "x" / scans everything readable and wastes time. Use find first to scope.
  • Reading a 5 MB file. Pagination handles it, but the agent often doesn’t realize it’s reading a giant file until it’s burned context on the first page. Use find -size to check before reading.
  • Binary files. grep and read_file skip binaries; the agent sees an empty/error result. If the agent is confused, it usually guessed at a filename that turned out to be binary.

​
See also