Building AI Agents with Bash and File Systems: Core Concepts and Engineering Practices

1. Introduction: Why We Need to Rethink Agent Construction

Large language model (LLM) applications have evolved from simple single-turn Q&A to autonomous agents capable of executing multi-step tasks. When it comes to building agents, there are two typical approaches in the industry. One is creating custom APIs and structured tool interfaces for each type of task. The other is letting the model directly use the most fundamental universal tools—such as the command line shell (Bash) and the file system—and combining them to accomplish complex tasks.

This latter philosophy touches upon several essential issues in agent design: tool granularity, context efficiency, and capability composability. This article will delve into this philosophy and provide a systematic technical overview of other key topics in agent engineering, such as Skills design, output format selection, and canary releases.

2. Why Bash and the File System: The Philosophy of a Minimal Toolset

2.1 Coverage of Universal Interfaces
The custom API approach defines a specific tool for each capability—e.g., one tool for reading files, one for writing, one for code search. The problem is that the number of tools bloats with demand. Each tool’s parameter schema, error handling, and edge cases require separate maintenance, and the model must learn how to use each one, consuming a significant amount of the token budget.

Bash, on the other hand, is a universal interface. Deleting files, text searching, process management, dependency installation, and build packaging can all be expressed via a single shell command. The file system serves as the most natural persistence layer: task states can be saved as JSON, intermediate artifacts can be written to disk, and data transfer between steps does not need to pass through the model’s context but can instead be referenced via file paths.

A representative agent tool definition looks roughly like this:

{
  "tools": [
    {
      "name": "bash",
      "description": "Execute shell commands in a controlled sandbox and return standard output and errors",
      "parameters": { "command": "string" }
    }
  ]
}

With just this one tool, an agent can complete the entire workflow of reading code, modifying code, running tests, and checking logs.

2.2 Composability Over Enumerability
The core of the Unix philosophy is “do one thing well and combine via pipes.” When an agent uses Bash, it inherits this composability. A pipe operation like grep -rn "TODO" src/ | wc -l, if implemented with dedicated tools, might require two tools plus a model-side data concatenation. With a shell, it is a single command and a single round trip. Every tool call requires a model inference, and the number of calls directly dictates latency and cost. Therefore, command-level composition has a distinct efficiency advantage.

2.3 Sandbox and Security Prerequisites
Giving a model a shell requires strict isolation. Common engineering practices include running commands in containers or micro-VMs, restricting network egress and file system mount scopes, setting resource quotas and execution timeouts, and making sensitive directories read-only. Only when the security boundary is sufficiently clear will the simplicity of a minimal toolset not translate into a risk exposure.

3. Context Management: The File System as External Memory

In long-running tasks, the model’s context is limited. How can an agent “remember” intermediate results? The file system provides a simple and effective answer:

1. Externalized plans: Write the to-do list derived from task decomposition into a file. Update it after completing each step. Even if the context is compressed, the model can re-read the plan to resume progress.
2. Results to disk: Write test outputs, build logs, and search results to files first. The model only needs to retain file paths and summaries, reading details on demand.
3. Structured notes: Use a fixed-format note file to record key decisions and findings, serving as cross-session knowledge accumulation.

This pattern of “pointers in context, data on disk” is a key technique for maximizing a limited token budget and is why the file system is indispensable in agent architecture.

4. Skills Design: Telling AI What It Doesn’t Know

In terms of expanding agent capabilities, a proven practice is the “skills package” mechanism: packaging operational knowledge, process specifications, and script templates within a specific domain into documents and resources that agents can load on demand. A core design principle is that skills packages should “tell AI what it doesn’t know,” rather than reiterating common knowledge the model already possesses.

At the design level, this means:

• Only write information the model cannot infer: internal system calling conventions, team-specific code standards, and implicit domain-specific processes.
• Describe trigger conditions: Clearly state “what scenarios should load this skill” to avoid irrelevant skills polluting the context.
• Provide executable assets: Instead of describing operational steps in long blocks of text, attach scripts directly so the agent executes rather than memorizes.

A good skills package is essentially an “operating manual for the agent,” and its quality standards are highly consistent with onboarding documents written for human new hires.

5. Presentation Layer: Why HTML Over Markdown

Another insightful perspective is that when agents need to generate interactive tools or complex data visualizations for users, HTML is more suitable than Markdown. The reasons can be understood on three levels:

1. Information density: Complex information often requires nested tables, collapsible panels, multi-column layouts, and color coding. Markdown’s expressiveness is clearly insufficient in these scenarios.
2. Interactivity: HTML pages can embed scripts and styles to directly generate filters, charts, forms, and other operable components, upgrading the agent’s output from “static descriptions” to “interactive tools.”
3. Zero build dependency: A single-file HTML requires no compilation or dependency installation and can be opened directly in a browser, making delivery costs virtually zero.

This does not mean Markdown should be entirely discarded. For plain text streaming output, code blocks, and lightweight lists, Markdown remains fast and efficient. A sensible division of labor is: use Markdown for documentary content and HTML for tool-based, visual content. The universal principle here is that output formats should serve the complexity and interactive needs of the information, not mere habit.

6. Engineering Release: Canary Strategies and User Communication

Agent products iterate quickly and exhibit high behavioral uncertainty, meaning release strategies must be carefully designed. A common industry practice is the canary release (gradual rollout): new features (such as voice interaction modes) are first rolled out to a small percentage of users, gradually expanding the scope while closely monitoring core metrics like success rate, latency, and user feedback. If anomalies occur, a quick rollback can be executed. The essence of canary releases is to confine uncertainty to the smallest possible blast radius.

Accompanying this is transparent user communication. When rate limiting, blocking strategies, or feature changes raise user questions, engineering teams explaining the reasons and boundaries directly on public channels builds more trust than silence or vague responses. The “explainability” of technical decisions is inherently part of the product experience.

7. Actionable Advice for Developers

Synthesizing the concepts above, we can distill an action checklist for agent developers:

1. Start with a minimal toolset: First give the agent a sandboxed shell and file system, observe its shortcomings in real tasks, and then consider supplementing it with dedicated tools.
2. Put state on disk, leave context for reasoning: Cultivate a habit of “persisting intermediate results to disk and re-reading as needed.”
3. Only write incremental knowledge in skills packages: Regularly review and delete content the model already knows.
4. Choose output formats based on information complexity: Delegate interaction and visualization to HTML, and lightweight text to Markdown.
5. Canary release all new features: Validate with small traffic, let metrics speak, and roll back quickly.
6. Sandbox first: Any design that allows the model to execute commands must be built on strict isolation and auditing.

8. Conclusion

The idea of “building agents with Bash and the file system” is worth emphasizing repeatedly because it reminds us that an agent’s capability ceiling does not come from the quantity of tools, but from the expressiveness of fundamental interfaces, the precision of context management, and the stability of security boundaries. For teams building agent applications, rather than chasing the expansion of the tool ecosystem, it is better to go deep on these foundational issues first—this is perhaps the most valuable experience practitioners can pass down to newcomers.