The Bash Agent

A probably unsafe, surely inefficient AI agent framework that runs entirely in Bash and talks to your local LLM.

What is this?

I am GPU poor. I use a Radeon RX 9060 XT and I can't wrap my mind around llama.cpp optimal run flags. Token generation is so slow that the popular agents crash or timeout. I could modify timeout length but Pi had the http connection buried deep in some npm dependancy, while Aider couldn't be convinced to connect to a local server without knowing the model beforehand. Skill issues? Sure.

So what's the solution? Simple: write an agent yourself. How hard can it be? This way you can put 2 hours of timeout in the http request.

Why bash?

Modern software has too many dependencies. Why not use something already present in all major UNIX systems? Bang! That's the idea. The only deps for this agent are:

• bash
• jq
• curl
• pandoc - optional

But I don't like bash

Neither do I. I daily drive fish, but bash is the standard, so if you really want, you can write your tools in any scripting language you prefer. Even Python. Or C.

Is this project an AI generated joke?

No, but the edit tool was generated by running the agent on its own source because I like to live dangerously.

Quick Start

1. Set up your local LLM server

Make sure you have an LLM server running on localhost:41080 (OpenAI-compatible API). Or customize ba-curl to connect where you want.

2. Run the agent

# Interactive mode - just start chatting!
./bash-agent

# Or pipe a question to it
echo "Which are 5 key events in the lore of Star Wars?" | ./bash-agent

How it works

1. You type (or pipe) your request
2. The agent talks to your local LLM
3. The LLM can request tools to run
4. Results come back and the LLM gives you a helpful response

Adding Your Own Tools

Want to extend what the agent can do? Just create a bash script in the lib/bash-agent/tools/ directory:

# Copy the template
cp tool-template.sh lib/bash-agent/tools/my-tool

# Make it executable
chmod +x lib/bash-agent/tools/my-tool

# Add your logic and you're done!

Check tool-template.sh for guidance.

Installing

The Makefile supports installing in different locations. Just run:

# Install locally, change destination as needed.
PREFIX=~/.local make install

# Install systemwide
sudo env PREFIX=/usr/local make install

You may require to add $PREFIX/bin to your $PATH.

Configuration

By default, the agent looks for tools in ./lib/bash-agent/tools.

That's it!

Keep it simple, keep it bash. 🚀

For more details, check out AGENT.md.