ai-explain : l'ELI5 des scripts et des erreurs, directement dans votre terminal

Vous avez cloné un repository et vous y trouvez un script Bash exécuté par le pipeline CI. Trois cents lignes, aucun commentaire. Vous devez comprendre ce qu'il fait avant de le modifier. Vous pouvez le lire attentivement, chercher la signification des flags, suivre la logique. Ou vous pouvez l'envoyer à ai-explain.

Même histoire pour les stack traces. Une erreur React en production avec six frames de sortie minifiée. Un Fatal error PHP à la ligne 847 d'un fichier que vous n'avez jamais ouvert. Un build Docker qui échoue sur une étape RUN que vous n'avez pas écrite.

ai-explain est la version terminal du composant de tooltip ELI5 de ce blog — la même idée « explique-moi comme si j'avais cinq ans », mais dans votre shell plutôt que dans le navigateur.

Expliquer un script que vous n'avez pas écrit​

$ 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.
▋

Voilà toute l'interaction : un chemin de fichier en entrée, une explication en langage clair en sortie — les prérequis, le tag d'image basé sur le hash du commit, le redémarrage avec --no-deps, le health check de 60 secondes et ce qui se passe en cas de timeout.

Pourquoi ça fonctionne​

ai-explain gère trois modes d'entrée, vérifiés dans cet ordre : l'entrée via pipe (donc cat file | ai-explain l'emporte toujours, même si un nom de fichier est aussi passé), un fichier existant, ou du texte inline pour une question rapide — une seule fonction couvre « explique-moi ce fichier » et « explique-moi cette erreur » sans commandes séparées à retenir. Le prompt demande quinze lignes de texte maximum, jamais une copie de l'entrée, et transmet uname -s pour que les commandes suggérées correspondent à la plateforme sur laquelle vous êtes réellement.

Installation​

Tout tourne sur votre machine : zsh, curl et jq (qui construit la requête envoyée à Ollama), et un serveur Ollama accessible — voir installer Ollama si vous n'en avez pas encore.

1. Créez les fichiers. Chaque fonction de cette série vit dans son propre fichier dans ~/.zsh/fns/. La commande ci-dessous crée ce dossier et les deux fichiers d'un coup — ou téléchargez le ZIP, ou créez chaque fichier à la main et collez-y son contenu. _ollama.zsh est la fondation partagée par toute la série, présentée dans ai-test : si un article précédent vous l'a déjà donné, la copie ici est le même fichier.

2. Chargez le dossier depuis ~/.zshrc. Déjà fait si vous avez suivi un article précédent de cette série. Sinon, ajoutez ces lignes à la fin de ~/.zshrc — elles sourcent chaque fichier .zsh du dossier, donc la prochaine fonction que vous ajouterez ne demandera aucune modification ici :

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

3. Ouvrez un nouveau terminal (ou lancez exec zsh dans celui en cours), et vérifiez que le shell connaît la nouvelle fonction :

type ai-explain

ai-explain is a shell function from …/ai-explain.zsh signifie que vous êtes prêt. ai-explain not found signifie qu'il manque l'étape 2.

Autres démos​

Expliquer une 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.
▋

Envoyer la sortie de n'importe quelle commande​

Le pattern le plus utile : lancez une commande qui échoue et envoyez sa sortie directement :

docker build . 2>&1 | ai-explain

npm install 2>&1 | ai-explain

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

Le 2>&1 redirige stderr vers stdout pour que les deux streams arrivent dans le pipe. Sans lui, les messages d'erreur de la plupart des outils CLI n'atteignent jamais ai-explain.

Pour les commandes qui produisent beaucoup de sortie, passez d'abord par tail pour ne garder que la fin pertinente (là où les erreurs atterrissent généralement).

Utilisation depuis le dispatcher ai​

Comme toutes les fonctions de cette série, ai-explain s'enregistre dans le registre AI_COMMANDS. Le dispatcher ai (issu de _ollama.zsh) liste chaque fonction enregistrée — ici avec les fonctions publiées de cette série installées :

$ 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)

Sélectionnez ai-explain et le dispatcher ouvre d'abord son sélecteur de fichiers fzf : AI_PARAMS[explain]="file" lui indique de demander un fichier plutôt qu'une ligne de texte.

Sous le capot (passez votre chemin si vous voulez juste l'utiliser)​

Quand ai-explain est le plus utile​

• Scripts hérités : comprendre ce que fait un script CI/CD avant de le modifier
• Erreurs inconnues : une stack trace d'un langage ou d'un framework que vous maîtrisez mal
• Sorties de log cryptiques : avertissements du daemon Docker, entrées du journal systemd, messages du kernel
• Archéologie de one-liners : cette commande awk '{ split($0,a,":"); ... }' trouvée dans un Makefile
• Vérification rapide : est-ce que ce script fait bien ce que son nom suggère ?

C'est aussi utile comme outil d'apprentissage : envoyez-lui un script que vous avez écrit vous-même et voyez si l'explication correspond à votre intention. Si ce n'est pas le cas, soit l'explication est fausse (ça arrive), soit le script contient un bug subtil.

Conclusion​

ai-explain rejoint la série « Ollama daily use ».

La série a commencé avec ai-test (la fondation : _ollama.zsh, le dispatcher, le registre AI_COMMANDS) et s'est enrichie de fonctions une par une — chacune résolvant un problème précis de workflow dans le terminal avec un LLM local :

• Workflow du développeur : ai-review, ai-secrets, ai-commit, ai-standup
• Opérations : ai-ci, ai-fix
• Assistance shell : ai-ask, ai-data, ai-diagram
• Travail documentaire : ai-translate, ai-summarize, ai-diff
• Votre propre documentation : ai-blog-search
• Explication : ai-explain

Toutes partagent la même fondation _ollama_query. Ensemble, elles couvrent les moments d'une journée de développement où vous iriez normalement chercher dans un navigateur ou une IA dans le cloud — mais où un modèle local est plus rapide d'accès et garde tout sur votre machine.

Les fonctions sans lien sont encore à venir. Lancez ai pour voir ce que votre terminal sait déjà faire.