How Agents Find Files

When I use coding agents such as Pi or Codex, I sometimes wonder how they find the right files to edit. Do agents pass every file name under the working directory to the LLM, or can the LLM search for files itself?

I ran an experiment to find out.

I created a small repo: https://github.com/wilkice/how-agent-find-files. It contains a simple Python script that demonstrates the behavior. I asked the agent to find the content of b.txt, but I did not give the LLM the full file path. When I ran the script, the logs showed how the agent searched for the file.

INFO:__main__:Running shell command: cat b.txt 2>/dev/null || echo "FILE NOT FOUND"
INFO:__main__:Running shell command: ls -la; echo "---"; find . -name "b.txt" 2>/dev/null

The file `b.txt` doesn't exist in the current directory (or anywhere on the system).

I checked the current working directory and ran a search for any file named `b.txt`, but there are no files with that name here. The files present are:

- `.env`
- `.env.example`
- `main.py`
- `pyproject.toml`
- `README.md`
- `uv.lock`
- and various hidden/config directories

Could you let me know which file you actually meant, or where `b.txt` should be located?

From this output, we can see that the agent first tried the current working directory. When b.txt was not there, it searched the repository. Since it still could not find the file, it stopped and asked for clarification.

So even when we do not specify the full path, the LLM can use a shell command to search for the file. If the file exists, this kind of search is usually enough to locate it.

There is another important detail. In another run, I saw this log:

INFO:__main__:Running shell command: cat b.txt 2>/dev/null || echo "FILE_NOT_FOUND"

INFO:__main__:Running shell command: find / -name "b.txt" 2>/dev/null

This searches from the root of my machine, which is bad. That is why agents need a harness that limits file access, or prompts that clearly constrain where the agent should search.

So why not send every file path in the directory in the system prompt?

The main reason is that working directories can be large and mutable. Files can be deleted or created during a session. If the system prompt includes a file list, the agent needs to keep that list current. Updating it repeatedly can also invalidate the prompt cache.

Also, if the agent needs to look outside the current directory, it still needs a search tool.

The result is that agents often find files by choosing and running search commands. I used Bash in this example, but many agents have dedicated file-search tools that are more powerful and efficient than this simple shell approach.