Purpose Butterfish is aimed at developers who work in the command line, embedding LLM capabilities directly into the shell (bash, zsh) so that users can get high-context AI help without copying and pasting, with a bias toward software engineering scenarios.
Main capabilities
- Ask AI questions directly in the terminal; any command starting with an uppercase letter is intercepted and sent to the model as a prompt.
- The AI can read shell history and command output, so it supports context questions such as "Why did that command fail?"
- Automatically completes shell commands; commands the AI has verbally suggested may appear in completions, and pressing Tab applies them.
- Goal Mode: commands starting with ! trigger agent mode, where the AI proposes commands and hands them to the user to execute, with the results sent back to the model; starting with !! executes directly without confirmation (there is risk).
- It can also be used as a general ChatGPT interface, for example "Give me a pasta recipe."
- It provides more granular command-line tools for prompting, generating commands, summarizing text, and managing local file embeddings.
- butterfish.nvim is a Neovim plugin that supports fluent LLM prompting within Neovim, for example rewriting a code block according to specified instructions.
How to use Supports MacOS and Linux, and can be installed via Homebrew or go install. On first run it prompts you to paste an OpenAI API key, and the key is written to ~/.config/butterfish/butterfish.env. You can alias the butterfish command (such as bf). Running butterfish shell starts a new shell instance and intercepts input and output. It uses the gpt-4-turbo model by default and can be configured to use other models; you can also use --base-url (-u) to point to any OpenAI-compatible API service, including local models. Prompt wrappers are stored in ~/.config/butterfish/prompts.yaml, visible and editable. Use butterfish shell -v to view raw AI request/response logs (on MacOS located at /var/tmp/butterfish.log), and -vv for more detail.
Applicable scenarios Suitable for developers who are used to working in the terminal, for quickly obtaining commands, troubleshooting command failure reasons, auto-completion, completing goals in an agentic way such as recursively listing golang files, finding hidden files, viewing the processes using the most memory, and also for general LLM conversations.
Limitations Goal mode is not stable; the official description says it is "quite hit-or-miss," and success depends on the complexity of the goal and how much guidance is given; the agent may favor commands from a specific version, may require trial and error on MacOS and Linux, and is also not good at handling large text files. Historical context is limited by the model's token window, and it tries to include recent history, using at most 512 tokens per history item, with overly long command output truncated. When running interactive subprocesses such as vim and ssh, Butterfish avoids interfering. The tool modifies the shell prompt by default to indicate status, and it is an experimental project.
