Principle 1: Bash Is the Key

"What if BASH is all you need?" — Andrew Qu, Vercel

The Vercel Discovery

Here's a story that changed how engineers think about building AI agents.

Vercel is the company behind Next.js, one of the most popular web frameworks. They host millions of websites and have some of the best engineers in the industry. When they decided to build an internal AI agent called d0 to answer data questions for their employees, they did what good engineers do: they engineered it properly.

The first version had specialized tools for different tasks. It had heavy prompt engineering to guide the AI's behavior. It had elaborate context management to keep track of what was happening. It was sophisticated.

It worked. Kind of. But it was fragile and slow.

Then they tried something radical. They stripped the agent down to a single capability: BASH.

What is BASH? It's the terminal on your computer. That black window where you can type commands. BASH (which stands for "Bourne Again Shell") lets you interact with your computer through text commands instead of clicking around. Commands like grep to search through files, cat to read file contents, ls to list what's in a folder.

Vercel gave their agent access to just these basic commands. Nothing fancy. Just the ability to explore files the way a programmer would.

The results surprised everyone:

Metric	Complex Design	BASH-Only Design
Execution time	274.8 seconds	77.4 seconds
Success rate	80%	100%
Token usage	~102k tokens	~61k tokens
Steps required	~12 steps	~7 steps

The simpler version was 3.5x faster, achieved 100% success rate, and used fewer resources. All by doing less.

This isn't a fluke. It reveals something fundamental about how General Agents work best.

The Unix Philosophy: Why Simpler Wins

To understand why BASH works so well, you need to understand a philosophy that's over 50 years old.

In the 1970s, engineers at Bell Labs developed Unix, an operating system that would eventually influence almost every computer you use today. They built it around a radical idea: simplicity through composability.

Instead of building one giant program that does everything, they built many small programs that each do one thing really well. Then they made it easy to connect these programs together, passing the output of one as the input to another.

This is the Unix philosophy:

1. Each tool does one thing well.

grep searches. That's all it does. It doesn't edit files, it doesn't organize them, it doesn't do anything else. It just searches, and it does that brilliantly.

cat reads files and shows you what's inside. That's it.

ls lists what's in a folder. Nothing more.

2. Tools connect through pipes.

You can chain these simple tools together. Want to find all lines containing "error" in your log files and count how many there are? Chain grep to wc:

grep "error" logs.txt | wc -l

The | symbol is called a pipe. It takes the output of grep and feeds it into wc (word count). Simple tools, combined to do complex things.

3. Everything is text.

Files are text. Command output is text. No special formats, no proprietary structures. This makes everything compatible with everything else.

Why This Matters for General Agents

So why does a 50-year-old philosophy matter for AI?

Models are smart. Modern LLMs don't need elaborate scaffolding. When you give them basic tools and room to reason, they often make better choices than pre-planned workflows allow. The Vercel team discovered that their complex tooling was actually getting in the way. The AI was smarter than their architecture gave it credit for.

Simplicity reduces failure. Every layer you add to a system is a potential breaking point. A custom "file search tool" might have bugs. A "context management system" might lose track of state. But grep? It's been doing text search for 50 years. It works.

These tools are battle-tested. Millions of programmers use these commands every day. Every edge case has been found and fixed. Every performance optimization has been made. Why build a custom solution when your operating system already has one that's been refined for decades?

What This Looks Like in Practice

Let's see how a General Agent actually uses BASH to get things done.

Reading and Exploring

Imagine you ask a General Agent: "What files do I have in my Documents folder related to the budget?"

Without terminal access, the AI could only tell you: "Try opening your file explorer and searching for 'budget'."

With terminal access, the agent can actually look:

ls -la Documents/

This command lists everything in your Documents folder. The -la flags mean "show all files, with details." The agent now sees your actual files, not a guess about what might be there.

Then it can search:

grep -r "budget" Documents/

This searches through every file in Documents (and all subfolders, that's what -r means) for the word "budget". The agent gets back a list of every file that mentions budget, with the exact lines where it appears.

Organizing and Managing

Now say you want to organize those budget files. The agent can:

mkdir -p Projects/Budget-2026/

This creates a new folder. The -p flag means "create parent folders if needed." So if Projects doesn't exist yet, it creates that too.

Then it can move files:

cp Documents/quarterly-report.xlsx Projects/Budget-2026/

This copies your quarterly report into the new folder. The agent can do this for each file it found, organizing your scattered documents into a sensible structure.

Iterating Until It Works

Here's where it gets interesting. General Agents don't just run one command and stop. They observe what happens and adjust.

Watch this sequence:

find ~/Downloads -name "*.pdf"

The agent runs this to find all PDF files in Downloads. But maybe it gets back unexpected results: some are in nested folders, some have weird names.

So it adjusts:

find ~/Downloads -name "*.pdf" -type f

Adding -type f means "only actual files, not folders." Better results.

Now it can organize them:

mkdir -p ~/Documents/PDFs/2026
mv ~/Downloads/*.pdf ~/Documents/PDFs/2026/

And verify:

ls ~/Documents/PDFs/2026/

Did it work? The agent checks. If something went wrong, it tries another approach.

This is the OODA loop you learned about earlier: Observe, Orient, Decide, Act. BASH is what makes this loop possible. Without the ability to run commands and see results, the agent can't iterate. It's stuck giving you instructions instead of actually helping.

Without Terminal Access vs. With Terminal Access

Let's make this concrete with a real scenario.

Without Terminal Access

You're working with a regular AI chatbot. You need to find all files related to your Q4 budget project and organize them.

You: "I need to find all files related to Q4 budget"

AI: "I'd suggest searching for 'budget' or 'Q4' in your file explorer.
     On Mac, you can use Spotlight. On Windows, use the search bar in
     File Explorer."

You: [You open Finder, search "Q4", wait for results]

You: "I found some files but they're scattered across Downloads,
     Desktop, and Documents"

AI: "You could create a new folder called 'Q4-Budget' and manually
     move the files there. Would you like step-by-step instructions?"

You: [You create the folder, then drag files one by one]

You: "Some files reference 'quarterly review' instead of Q4"

AI: "Good catch! Try searching for that term too and add those
     files to your folder."

You: [Search again, find more files, drag those too]

This takes 15-20 minutes of your time. The AI is helpful, but you're doing all the actual work.

With Terminal Access

Same scenario, but now the AI is a General Agent with BASH access.

You: "Find all files related to Q4 budget and organize them"

Agent: [runs: find ~ -type f \( -iname "*budget*" -o -iname "*Q4*"
       -o -iname "*quarterly*" \) 2>/dev/null]

       "I found 23 files across your Documents, Downloads, and Desktop
       folders. Here's what I found:
       - 8 spreadsheets (.xlsx)
       - 11 documents (.docx, .pdf)
       - 4 email exports (.eml)

       I'll create an organized structure. Does this look right?

       ~/Projects/Q4-Budget/
       ├── Spreadsheets/
       ├── Documents/
       └── Communications/"

You: "Yes, go ahead"

Agent: [runs: mkdir -p ~/Projects/Q4-Budget/{Spreadsheets,Documents,Communications}]
       [runs: mv commands for each file type]
       [runs: ls -la ~/Projects/Q4-Budget/]

       "Done. All 23 files organized. Here's the final structure..."

Three minutes. The agent did the searching, found related terms you might have missed, created a sensible structure, and verified everything worked.

The difference isn't just speed. It's that the agent can actually help instead of just advising.

Safety and Permissions

At this point you might be thinking: "Wait, I'm giving AI access to run commands on my computer? That sounds dangerous."

You're right to be cautious. Terminal access is powerful, and powerful tools need safeguards.

Well-designed General Agents handle this through a permission system. Not all commands are treated equally.

Read-only commands run freely. When the agent wants to look at what files exist or search through content, that's safe. It's just looking, not changing anything.

ls -la Documents/       # Just looking at what's there
cat meeting-notes.txt   # Just reading a file
grep "budget" *.txt     # Just searching
find . -name "*.pdf"    # Just finding files

These commands can't hurt anything. The agent runs them immediately to gather information.

Commands that change things ask for permission. When the agent wants to create, move, or especially delete files, it pauses and asks you first.

mkdir Projects/NewClient/    # Creates a folder - usually asks
mv report.txt Reports/       # Moves a file - asks for confirmation
rm old-draft.txt             # Deletes a file - definitely asks

You see exactly what the agent wants to do and approve it before it happens.

Dangerous commands require you to run them yourself. Some operations are too risky for any automated system. Things like deleting entire folders recursively (rm -rf) or running commands with admin privileges (sudo). A well-designed agent won't even attempt these. It will tell you what needs to happen and let you decide whether to do it manually.

Here's a simple way to think about risk levels:

What the Command Does	Examples	How It's Handled
Just reads or searches	ls, cat, grep, find	Runs automatically
Creates something new	mkdir, touch	Usually runs, you can review
Moves or renames	mv, file edits	Asks for confirmation
Deletes things	rm, bulk operations	Explicit approval required
System-level changes	rm -rf, sudo	You do it yourself

The goal is confident collaboration. You trust the agent to explore and gather information freely. You stay in control of anything that changes your files. And you keep full authority over anything dangerous.

Start with read-only operations to build trust. As you see the agent make good decisions, you can give it more autonomy. But always keep the ability to review destructive operations before they happen.

The Core Insight

Let's step back and see what we've learned.

Vercel's discovery wasn't really about BASH specifically. It was about simplicity. Their complex agent architecture, with specialized tools and elaborate prompts and heavy metadata, performed dramatically worse than a simple agent with just file system access.

This pattern shows up again and again in General Agent design:

Simple foundations outperform complex architectures. The Unix tools that power BASH have been refined for 50 years. They're fast, reliable, and handle edge cases gracefully. Custom tools, no matter how cleverly designed, can't match that maturity.

Models reason better with room to breathe. When you constrain an AI with rigid workflows, you limit its ability to adapt. When you give it simple tools and let it figure out how to combine them, it often finds better solutions than you would have prescribed.

Every principle in this chapter builds on this one. Terminal access is what makes the other principles possible:

• Principle 2 (Code as Universal Interface): You can only write and run code if you have terminal access.
• Principle 3 (Verification as Core Step): You can only verify results if you can run commands and check output.
• Principle 4 (Small, Reversible Decomposition): You can only break work into small steps if each step can be executed and observed.
• Principle 5 (Persisting State in Files): You can only save state to files if you can write files.
• Principle 6 (Constraints and Safety): The permission model only matters if there are real operations to permit or deny.
• Principle 7 (Observability): You can only observe what the agent is doing if it's actually doing things.

BASH is the key that unlocks everything else. Without it, a General Agent is just a chatbot giving advice. With it, the agent becomes a true collaborator that can observe your world, reason about it, and take action.

Try With AI

Prompt 1: Experience the difference

Here's a task I do manually that involves files on my computer:
[describe something like: organizing downloads, finding old documents,
creating folder structures for projects, compiling information from
multiple files]

First, tell me how you'd help if you could only give me instructions
to follow (no file access).

Then, tell me how you'd approach it with direct file system access.

What's the actual difference in how we'd work together?

Prompt 2: Understand command safety

I'm learning to work with AI that has terminal access.
Help me understand the safety levels of these commands:

- ls -la ~/Documents
- cat notes.txt
- cp report.txt backup.txt
- mv Downloads/*.pdf Documents/
- rm old-draft.txt
- rm -rf ~/Projects/old/

For each one: What does it do? What could go wrong?
How should I think about approving or denying it?

Prompt 3: Apply the simplicity principle

I want to [describe a file-related task].

Before we start: what's the simplest approach using basic commands
like ls, cat, grep, find, cp, mv, and mkdir?

Don't build anything complex. Show me how Unix philosophy
(simple tools that combine) applies to this task.