Files over Tools: Rethinking AI Agent Architecture with a Virtual Filesystem

Introduction: A Paradigm Shift in Agent Architecture

In recent years, AI Agents have become a central pillar of large language model applications. The vast majority of Agent frameworks follow the same design philosophy: define a set of discrete "tools" for the model, where each tool maps to a function call — think search_web, read_database, or send_email. The model selects the appropriate tool for a given task and executes it via structured function calling.

Function Calling is one of the core capabilities of modern LLMs, first introduced by OpenAI in June 2023 alongside the GPT-3.5/GPT-4 API. The mechanism works like this: developers describe available functions — their names, parameter types, and purposes — to the model using JSON Schema. When the model determines during inference that a function call is needed, it outputs structured JSON rather than natural language; the application layer parses that JSON, executes the corresponding function, and returns the result to the model to continue reasoning. This design decouples the model's "intent" from its "execution," enabling LLMs to interact reliably with external systems. However, each tool's JSON Schema description can consume anywhere from dozens to hundreds of tokens, and when the number of tools exceeds 30–50, the tool definitions alone can eat thousands of tokens from the context window — directly squeezing the space available for actual reasoning.

Yet this "tools-first" paradigm comes with a real cost. As task complexity grows, so does the number of tools. The model must choose among dozens or even hundreds of tool definitions, the context fills up with tool descriptions, and error rates climb accordingly. An article titled Files over Tools that sparked widespread discussion on Hacker News put forward a counterintuitive argument: instead of giving an Agent more and more specialized tools, give it a virtual filesystem and a bash environment.

From "Tools" to "Files": The Core Idea

The article's central claim can be summarized in one sentence: what an Agent truly needs is not more tools, but a general-purpose operating environment.

The Tool Bloat Problem

In the traditional architecture, developers must predefine a tool interface for every possible operation. This creates three fundamental problems:

• Context overhead: Every tool's JSON Schema definition consumes tokens. The more tools there are, the less context remains for actual task reasoning.
• Poor composability: Tools are hard to combine freely. Piping the output of one tool into another typically requires additional orchestration logic.
• Limited expressiveness: Predefined tools only cover scenarios the developer anticipated. Edge cases leave the Agent stuck.

A Virtual Filesystem as a Unified Abstraction

The Files over Tools proposal introduces a virtual filesystem that the Agent interacts with via bash commands. In this design:

• Data is no longer passed through tool return values — it lives as files in the filesystem;
• The Agent reads, writes, and processes files using familiar Unix tools like ls, cat, grep, sed, and pipes;
• Complex operations can be freely composed with shell scripts, with no need to define a new tool for every possible combination.

This "everything is a file" philosophy is essentially a transplant of Unix thinking into AI Agent architecture.

The Unix philosophy was established by Ken Thompson and Dennis Ritchie at Bell Labs in the 1970s while building the Unix operating system, later summarized by Doug McIlroy into a few core principles: "Make each program do one thing well" and "Make the output of every program the input of another." The most influential design decision was "everything is a file" — whether it's a regular file, a directory, a hardware device, a network socket, or inter-process communication, everything is accessed through a unified file descriptor interface. The pipe (|) mechanism lets multiple small tools chain together freely, allowing simple commands to compose into remarkably complex data-processing workflows. This philosophy has kept Unix/Linux dominant in the server world to this day, and bash — as the primary interface for this philosophy — carries decades of accumulated ecosystem knowledge and usage examples.

Why This Design Aligns with the Model's "Intuition"

A key insight here is that modern LLMs were exposed to enormous quantities of Unix commands, shell scripts, and file operation code during pretraining. Compared to the custom tool APIs that vary from project to project, bash and the filesystem are domains the model has already deeply internalized.

Modern LLMs (such as GPT-4, Claude, and the Llama series) are typically pretrained on datasets containing trillions of tokens, including vast amounts of code from GitHub repositories, Stack Overflow Q&As, Linux documentation, and technical blogs. It's estimated that public GitHub repositories contain billions of lines of shell scripts, Makefiles, and command-line examples — meaning models carry rich prior knowledge of the syntax and idioms of tools like grep, awk, sed, xargs, and find. By contrast, the custom tool APIs of any given Agent framework are virtually never present in pretraining data, so the model must rely entirely on the documentation provided in the prompt to use them correctly.

This means:

• Models naturally succeed at bash more often, because they've seen countless real-world command-line examples;
• No need to exhaustively explain each tool's usage in the prompt — the model already has strong priors;
• For multi-step processing tasks, the model can behave like a real engineer, chaining simple commands into complex workflows with pipes and scripts.

In other words, this design brings the Agent closer to how a developer works in a terminal — rather than confining it to an operations panel with fixed buttons.

The Engineering Value of a Virtual Filesystem

Virtualizing the filesystem is another major highlight of this approach. A virtual filesystem doesn't directly map to the host machine's actual disk — it's a controlled sandbox environment that delivers three important engineering benefits:

Security Isolation

All bash commands the Agent executes are confined within the virtual environment, unable to touch sensitive files on the host system — effectively reducing the security risks of arbitrary code execution.

Allowing an AI Agent to run arbitrary bash commands is a double-edged sword, making security isolation a central engineering challenge. The industry's mainstream sandboxing approaches operate at several layers: container-level isolation (e.g., Docker) uses Linux namespaces and cgroups to confine processes to an isolated filesystem and network space; stricter solutions use lightweight VM technologies like gVisor or Firecracker to add another layer of isolation between the container and the host kernel; system call filtering (seccomp) can further restrict kernel calls a process is allowed to make using an allowlist. OpenAI's Code Interpreter, Anthropic's Claude artifact execution environment, and dedicated code sandbox services like E2B and Modal have all solved this problem in production. The virtual filesystem approach advocated by Files over Tools needs to be built on top of these sandboxing technologies to be truly safe and usable.

State Persistence

Intermediate results are saved as files, allowing the Agent to maintain state across multiple steps. If one step fails, it can retry from the existing files rather than starting over from scratch.

Observability and Debuggability

For developers, the filesystem state is fully transparent. You can inspect at any time which files the Agent has generated and what they contain — far more intuitive than tracing a sequence of abstract tool calls.

Trade-offs and Debates: Not a Silver Bullet

Despite its appeal, there are several practical trade-offs worth considering from an engineering perspective:

• Precise control vs. freedom: The advantage of predefined tools is predictable, constrained behavior. Opening up bash access means the Agent may perform operations beyond what was intended, requiring more robust sandboxing and permission management.
• Cases that demand deterministic interfaces: When calling external APIs or enforcing strict parameter validation, structured tool calling remains more reliable. Files and bash are better suited to "glue" tasks like data processing and text manipulation.
• Error handling challenges: Shell command error messages can be cryptic. The Agent needs the ability to parse error output and self-correct.

A more pragmatic approach, therefore, may be a hybrid architecture: use the filesystem and bash for flexible data manipulation, while retaining a small number of critical structured tools for interfacing with external services. This idea already has real-world precedents in the industry — Anthropic's Computer Use feature for Claude lets the model directly interact with desktop environments while retaining structured API calling capabilities; OpenAI's Assistants API similarly supports mixing Code Interpreter (essentially a Python execution sandbox) with custom Function Calling. In the open-source community, LangChain's ShellTool, the smolagents framework, and the OpenHands project (formerly OpenDevin) have all explored Agent architectures centered on bash execution, supplemented by a small number of structured tools. The core principle of hybrid design is: use structured tools wherever you need a stable contract with an external service (e.g., payment APIs, database writes), to ensure reliable parameter validation and error handling; delegate data processing, text transformation, and file operations — the "glue" tasks — to bash and the filesystem, fully leveraging the model's prior knowledge.

Conclusion: Returning to Universal Abstractions

The value of Files over Tools lies not in providing a ready-made framework, but in challenging the reflexive habit of "piling on more tools" that pervades current Agent design. It reminds us that the most powerful abstractions are often the most universal ones.

Unix dominated the operating system world for decades with its "everything is a file" and "compose small tools" philosophy. That the same ideas are finding new life in the AI Agent space today may be no coincidence. When a model is smart enough to use a terminal the way a human does, what we may need to give it isn't more specialized buttons — it's an open, familiar workbench, and then the freedom to get to work.

For developers building Agents today, this is at least a direction worth seriously considering: before adding the next tool, ask yourself — can this operation be accomplished with just a file and a single line of bash?