Why a Single run() Tool with Unix Commands Beats Function Calling for AI Agents

A developer with two years of experience building AI agents—first as backend lead at Manus, then on open-source projects Pinix and agent-clip—has concluded that a single run(command="...") tool with Unix-style commands works better than traditional function calling approaches.

The Unix-LLM Convergence

The core insight is that Unix's 50-year-old design decision—everything is a text stream—aligns perfectly with LLMs' text-based nature. Unix programs communicate through text pipes, use --help for self-description, report success/failure with exit codes, and communicate errors through stderr. LLMs similarly understand only text tokens. This makes Unix's text-based interface a natural fit for LLMs, which essentially function as terminal operators with extensive exposure to shell commands in their training data.

The Single-Tool Approach

Most agent frameworks provide LLMs with a catalog of independent tools like [search_web, read_file, write_file, run_code, send_email, ...], requiring the LLM to make tool selection decisions before each call. As more tools are added, selection accuracy drops as cognitive load shifts from "what do I need to accomplish?" to "which tool?"

The alternative approach uses one run(command="...") tool that exposes all capabilities as CLI commands:

run(command="cat notes.md")
run(command="cat log.txt | grep ERROR | wc -l")
run(command="see screenshot.png")
run(command="memory search 'deployment issue'")
run(command="clip sandbox bash 'python3 analyze.py'")

Command selection becomes string composition within a unified namespace rather than context-switching between unrelated APIs.

Why CLI Commands Work Better

CLI commands are the densest tool-use pattern in LLM training data, appearing in billions of lines on GitHub (README install instructions, CI/CD build scripts, Stack Overflow solutions). The developer notes: "I don't need to teach the LLM how to use CLI—it already knows."

Compare approaches for the same task:

Task: Read a log file, count the error lines

Function-calling approach (3 tool calls):
1. read_file(path="/var/log/app.log") → returns entire file
2. search_text(text=, pattern="ERROR") → returns matching lines
3. count_lines(text=) → returns number

CLI approach (1 tool call):
run(command="cat /var/log/app.log | grep ERROR | wc -l") → "42"

One call replaces three because Unix pipes natively support composition. The developer emphasizes that this isn't special optimization but leveraging Unix's existing design.