How matheusml/zsh-ai works
Project type and purpose
• This is an open-source, lightweight zsh plugin (“zsh-ai”) that lives entirely in the terminal.
• Purpose: Transform natural-language prompts into shell commands by calling either a cloud AI (Anthropic Claude) or a local model (Ollama).
File structure
Top-level:
• zsh-ai.plugin.zsh – plugin entrypoint that hooks into zsh.
• lib/ – core library modules, each implemented as a separate .zsh file:
– config.zsh • loads/validates environment variables
– context.zsh • inspects cwd/git status to build prompt context
– utils.zsh • JSON escaping, helper functions
– widget.zsh • zle widget that binds “#” to trigger AI call
– providers/ • anthropic.zsh & ollama.zsh implement two pluggable backends
• tests/ – unit tests for each module, ensuring reliability
• .github/workflows/test.yml – CI pipeline that runs tests on push
README for additional insights
• Core flow: user types “# some task” → widget intercepts → context + config assembled → provider module formats request → sends to Anthropic API or local Ollama endpoint → parses JSON → returns a shell command → prints into the shell.
• No external dependencies aside from optional jq for JSON parsing.
Detail without over-splitting
• Module but group low-level helpers (utils, JSON escape) under “Utility layer.”
• Both provider paths (Anthropic vs. Ollama) branching from a common “Provider” interface.