> ## Documentation Index
> Fetch the complete documentation index at: https://internal.september.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# File search

> Searching across files inside the Engine's sandbox.

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

| Tool          | Purpose                                                                                            |
| ------------- | -------------------------------------------------------------------------------------------------- |
| `grep`        | Regex search across files. Returns matching lines with file path and line number. Fast, exact.     |
| `find`        | Filesystem traversal by name pattern, type, time, size.                                            |
| `read_file`   | Read a specific file by path. Returns the contents (with size cap).                                |
| `file_search` | Semantic + keyword hybrid search across a directory. Useful when you don't know the exact pattern. |

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:

```
1. grep "def handle_login" src/  → returns auth.py:42
2. read_file src/auth.py        → reads the function
```

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:

```
1. find . -name "*.py" -newer 7d → recent Python files
2. grep ... in those files only
```

### 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:

```
1. file_search "rate limit handling" → ranked list of relevant files
2. read_file the top-ranked one
```

`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

* [Code execution](../../capabilities/code-execution) — sandbox
  guarantees that apply to all file tools.
* [Defining tools](../defining-tools) — wrap a specialized search for
  your codebase.