2026
why
a shell command explainer — deterministic parsing, with an AI layer that knows when it's guessing.
why
most "explain this command" tools forward your command to an LLM and hope for the best. that works, but it's non-deterministic: the same command can get different, sometimes wrong, explanations, and there's no record of why a flag was called dangerous. why splits the problem so the facts and the phrasing come from different places.
the problem
most tools that explain a command just ask an LLM to explain it, raw text in, prose out. that bothered me: the model has no real understanding of what --hard versus --soft actually does, it's pattern-matching on training data that includes a lot of correct git tutorials, and a fair number of wrong ones. i wanted the explanation to be grounded in something deterministic first, with the model doing only the part it's actually good at: turning structured facts into readable language.
architecture
why parses a command against a small hand-built knowledge base (git and docker, for now) that maps each subcommand and flag to its actual effects — what changes in git's history, the working tree, the index. that parsing step is pure logic, no AI involved, and it's what decides whether a --hard reset shows a destructive warning: the warning is tagged to the flag in the knowledge base, not inferred by a model.
only after that structured breakdown exists does an LLM (via Groq) get called, and only to translate the structured facts into a short plain-english explanation. the prompt it receives is built from the parsed fields, not the raw command string, so the explanation can't drift from what was actually parsed.
for commands outside the knowledge base, why falls back to asking the model directly — but the response is visibly marked 'inferred' rather than 'verified', so the two kinds of answer are never presented as the same kind of confidence.
what i learned
the earliest bug taught me the most: the effects list was showing every possible effect for a subcommand regardless of which flags were actually used, so a plain --soft reset was displaying a warning that only applies to --hard. it only surfaced because i tested by hand instead of trusting that green tests meant correct behavior — the tests just hadn't been written to check that specific thing yet.
the second lesson was operational, not algorithmic: a model id i'd hardcoded (llama-3.1-8b-instant) got deprecated by Groq mid-build, and every request started failing with a 404 that had nothing to do with my code. it's a small reminder that anything calling an external model is a dependency like any other — it can change under you.
what broke
the effects-leaking-across-flags bug above. also, briefly, forgetting that setting an environment variable in one terminal window doesn't carry over to a different one — cost more debugging time than it should have before i added automatic .env loading specifically to remove that failure mode entirely.
what's next
expanding the knowledge base beyond git and docker, and adding rate-limit-aware feedback so the fallback path degrades gracefully under load rather than just erroring.
all projects