How to Build AI Agents Using the Filesystem and bash

Rather than building complex custom tools to provide agents with the information they need, using the Filesystem and bash tools is far more efficient. LLMs have already learned directory navigation and file management via grep and similar commands from vast amounts of code, so providing data in a file structure lets them process information the same way they navigate code.

This approach overcomes the limitations of traditional Prompt stuffing and Vector search. While vector search excels at semantic similarity, it is weak at precise value extraction, whereas the filesystem can locate exact values through Unix commands. Additionally, since the agent only reads the files it needs on demand, context can be kept to a minimum.

In practice, Vercel applied this architecture to lower the cost of its sales call summarization agent from about $1.00 to $0.25 based on Claude Opus 4.5, while also improving output quality.

The key advantages are as follows:

• Precise retrieval: Exact data extraction is possible via grep, find, awk, and more
• Low maintenance cost: No need to build separate retrieval pipelines for each data type—just define the file structure
• Security: Can be run in a Sandbox environment, isolated from production systems
• Ease of debugging: You can directly see the commands the agent ran and the files it read, preventing black-box behavior