ai-explain: ELI5 for Scripts and Errors, Right in Your Terminal

You cloned a repository and found a Bash script that runs as part of the CI pipeline. Three hundred lines, no comments. You need to understand what it does before you modify it. You could read it carefully, look up the flags, trace the logic. Or you could pipe it through ai-explain.

Same story for stack traces. A React error in production with six frames of minified output. A PHP Fatal error at line 847 of a file you've never opened. A Docker build failure on a RUN step you didn't write.

ai-explain is the terminal counterpart to the ELI5 tooltip component on this blog — the same "explain like I'm five" idea, but for your shell instead of the browser.

Explain a Script You Didn't Write​

$ ai-explain deploy.sh

This script automates deploying an application using Docker and Docker Compose. It first checks that `docker`, `git`, and `curl` are installed, exiting if any are missing. It pulls the latest code from the `main` branch and builds a new Docker image tagged with the current git commit hash. Then it starts the app service in detached mode without restarting dependent services. After starting the service, it waits up to 60 seconds (12 attempts of 5 seconds each) checking if the app responds with HTTP 200 at `/health`. If successful, it prints a success message and exits. If the health check fails after all attempts, it reports the failure and exits with error code 1. The script modifies the local Docker environment by building a new image and starting containers, but doesn't change any files on disk except through Git operations. Risks include failing to start the app or timing out if the service takes longer than 60 seconds to become healthy. To fix potential issues, ensure all prerequisites are installed and the app's health endpoint is correctly configured.
▋

That's the entire interaction: a file path in, a plain-English breakdown out — prerequisites, the commit-hash image tag, the --no-deps restart, the 60-second health check and what happens when it times out.

Why It Works​

ai-explain handles three input modes, checked in this order: piped input (so cat file | ai-explain always wins even if a filename is also passed), an existing file, or inline text for a quick one-liner — one function covers "explain this file" and "explain this error" without separate commands to remember. The prompt asks for at most fifteen lines of plain text, never a copy of the input, and passes uname -s along so suggested commands match the platform you're actually on.

Installing It​

Everything runs on your machine: zsh, curl and jq (which builds the request sent to Ollama), and an Ollama server you can reach — see installing Ollama if you don't have one yet.

1. Create the files. Every function of this series lives in its own file in ~/.zsh/fns/. The one-liner below creates that folder and the two files in one go — or download the ZIP, or create each file by hand and paste its content. _ollama.zsh is the foundation the whole series shares, introduced in ai-test: if an earlier article already gave it to you, the copy here is the same file.

2. Load the folder from ~/.zshrc. Already done if you followed an earlier article of this series. Otherwise, add these lines at the end of ~/.zshrc — they source every .zsh file in the folder, so the next function you add needs no change here:

for fn_file in ~/.zsh/fns/*.zsh; do
  source "$fn_file"
done

3. Open a new terminal (or run exec zsh in the current one), and check that the shell knows the new function:

type ai-explain

ai-explain is a shell function from …/ai-explain.zsh means you're ready. ai-explain not found means step 2 is missing.

More Demos​

Explain a stack trace​

$ ai-explain example-error.txt

The error happens because the code tries to call `.map()` on a variable that is `undefined` in the ProductList component. This occurs at line 42 of ProductList.jsx where it expects an array but gets nothing.

To fix this, add a check to ensure the data exists before mapping:
```jsx
{products && products.map(product => (
  <div key={product.id}>{product.name}</div>
))}
```

If `products` is undefined, the component won't crash and will render nothing instead of throwing an error.
▋

Pipe any command output​

The most useful pattern: run a command that fails and pipe its output directly:

docker build . 2>&1 | ai-explain

npm install 2>&1 | ai-explain

./run-tests.sh 2>&1 | tail -50 | ai-explain

The 2>&1 redirects stderr to stdout so both streams reach the pipe. Without it, error messages from most CLI tools never make it to ai-explain.

For commands that produce a lot of output, pipe through tail first to keep only the relevant end of the output (where errors usually land).

Use from the ai dispatcher​

Like every function in this series, ai-explain registers itself with the AI_COMMANDS registry. The ai dispatcher (from _ollama.zsh) lists every registered function — here with the published ones from this series installed:

$ ai

ai >
  ai-blog-search — ask your blog a question (RAG over every published article)
  ai-commit  — draft a Conventional Commits message from staged changes
  ai-data <file.json|file.csv>  — suggest jq/awk commands tailored to this file
  ai-diagram <description>|<file>  — turn a description or a config file into a Mermaid diagram
  ai-explain [file|text]  — explain a script, an error or piped output in plain English
  ai-review  — code review of staged changes (SOLID, magic constants, naming)
  ai-secrets  — scan staged changes for hardcoded credentials
  ai-summarize <file> [points]  — summarize a document locally (default: 5 points)
  ai-test <file.sh|.php|.py>  — generate or complete a unit test suite
  ai-translate <file> [language]  — translate a document locally (default: French)

Select ai-explain and the dispatcher opens its fzf file picker first: AI_PARAMS[explain]="file" tells it to ask for a file rather than a line of text.

Under the Hood (skip this if you just want to use it)​

When ai-explain is most useful​

• Inherited scripts: understanding what a CI/CD script does before modifying it
• Unfamiliar errors: a stack trace from a language or framework you don't know well
• Cryptic log output: Docker daemon warnings, systemd journal entries, kernel messages
• One-liner archaeology: that awk '{ split($0,a,":"); ... }' command you found in a Makefile
• Quick sanity check: does this script do what the filename suggests?

It's also useful as a learning tool: pipe a script you wrote yourself and see if the explanation matches your intent. If it doesn't, either the explanation is wrong (it happens) or the script has a subtle bug.

Conclusion​

ai-explain joins the "Ollama daily use" series.

The series started with ai-test (the foundation: _ollama.zsh, the dispatcher, the AI_COMMANDS registry) and added functions one by one — each solving a specific terminal workflow problem with a local LLM:

• Developer workflow: ai-review, ai-secrets, ai-commit, ai-standup
• Operations: ai-ci, ai-fix
• Shell assistance: ai-ask, ai-data, ai-diagram
• Document work: ai-translate, ai-summarize, ai-diff
• Your own documentation: ai-blog-search
• Explanation: ai-explain

All of them share the same _ollama_query foundation. Together they cover the moments in a development day where you'd normally reach for a browser search or a cloud AI — but where a local model is faster to reach and keeps everything on your machine.

The functions without a link are still to come. Run ai to see what your terminal already knows how to do.