I Built a Terminal AI Companion in 300 Lines of Pure Bash — And It's MIT Licensed

I write a lot of bash scripts. Most of them work. Some of them don’t — and when they don’t, I spend 20 minutes staring at an error message that, in retrospect, was actually pretty obvious.

I figured: what if I could just ask an AI, from my terminal, what went wrong?

That’s bashbuddy. 300 lines of pure bash. No npm. No Python. No dependencies beyond curl and jq. MIT licensed, free forever.

What It Does

# Interactive chat mode — like having a senior engineer at your desk
bashbuddy

# Explain a pasted error
bashbuddy --explain < error.log

# Review a script for bugs before you run it
bashbuddy --review deploy.sh

# Natural language to bash command
bashbuddy --translate "show me disk usage sorted by size"

# Fix a bad command
bashbuddy --fix "rm -rf /"

That’s it. No Electron app. No Python framework. It’s literally a bash script you pipe things to.

The Interactive Mode

Run bashbuddy with no arguments and you get a REPL:

  bashbuddy v1.0.0 | Ctrl+D to quit | /help for commands

bb > why is my Nginx reverse proxy returning 502?

Your Nginx is returning a 502 Bad Gateway error, which means...

    [explanation with context and fix]

bb > write a script to find files modified in the last 24 hours

Here's a script that does that...

    #!/bin/bash
    find /path -type f -mtime -1 ...

The REPL remembers your conversation history across sessions. It knows what OS you’re on, what shell, what directory you’re in. Context-sensitive help, basically.

Special Commands

Works With Any AI Backend

I didn’t want to lock anyone into a specific provider. bashbuddy works with:

• OpenRouter — 100+ models, one API (my recommendation: Claude Haiku for speed)
• OpenAI — direct, reliable
• Groq — extremely fast, generous free tier
• LM Studio — run open-source models locally, fully offline
• Ollama — run open-source models locally, fully offline
• Any OpenAI-compatible API — bring your own endpoint

The setup wizard detects LM Studio and Ollama automatically if they’re running locally:

$ bashbuddy --setup
Choose backend [1]: 4   # LM Studio
Detected model: llama-3.2-3b-instruct
Config saved. Done.

One-Line Install

curl -fsSL https://raw.githubusercontent.com/JRone-git/pragmatic-sysadmin/main/bashbuddy/bashbuddy \
  -o ~/bin/bashbuddy && chmod +x ~/bin/bashbuddy

bashbuddy --setup

Requires: bash, curl, jq — already on most systems.

What 300 Lines Gets You

I wrote it to be readable, not clever. The entire source is one file. Here’s the rough architecture:

Config loading          ~40 lines  (env vars, XDG paths, API key)
Dependency check        ~10 lines  (curl, jq)
Setup wizard            ~60 lines  (backend detection, auto-detect local models)
System prompt builder   ~20 lines  (OS, shell, hostname, working dir)
API caller              ~40 lines  (curl, error parsing, HTTP code hints)
Message builder         ~50 lines  (history loading, JSON assembly with jq)
Streaming output        ~40 lines  (SSE parsing, token-by-token rendering)
Interactive REPL        ~60 lines  (input loop, built-in commands)
CLI parser              ~20 lines  (--explain, --review, etc.)

No external libraries. No package manager. You can read the whole thing in 10 minutes.

What It Doesn’t Do

Honest limitations:

• No background jobs — it’s synchronous, it blocks while waiting for the API
• No code execution — it explains and suggests, doesn’t run your code for you (though the $RUN: directive lets it offer commands for you to run manually)
• No multi-model conversations — each session uses one model
• No plugins — it’s intentionally small

If you need more, use a full CLI tool. bashbuddy is for the 90% case: “what does this error mean?” and “write me a quick one-liner.”

The $RUN Directive

One thing I’m proud of: if bashbuddy suggests a command to run, it doesn’t just dump it in the response. It uses a $RUN: prefix and waits for confirmation:

bb > find all large log files

That command would be:

    $RUN: find /var/log -name "*.log" -size +100M -exec ls -lh {} \;

Run this command? [y/N]

This is intentional. It’s a CLI tool. You should always know what’s about to run.

Why MIT Instead of GPL?

Because I want this to live in /usr/local/bin on servers, in Docker containers, in dotfile repos, everywhere. GPL would require anyone who modifies it to open-source their changes. MIT says: use it however you want, modify it, ship it, no strings attached.

The worst thing a developer tool can be is a walled garden.

The Code Is On GitHub

All of it. MIT licensed. Issues welcome, PRs doubly so.

Source: github.com/JRone-git/pragmatic-sysadmin/tree/main/bashbuddy

If you want to follow the development, the Buddy companion app (the elderly-friendly phone app) is in the same repo: pragmaticsysadmin.help/buddy — also MIT licensed, also free forever.