Butterfish

Butterfish Shell: CLI Tools for LLMs

Butterfish Shell is a command-line tool that adds AI prompting capabilities directly to your shell (bash, zsh) via OpenAI-compatible APIs. It functions like GitHub Copilot for the terminal, enabling high-context AI help and automation without copy-paste. When you type a command starting with a capital letter, Butterfish sends the current shell context to the AI for generating commands, debugging, or answering questions. It includes an autosuggest feature, a Goal Mode agent, and a Neovim plugin for in-editor prompting. The project is open source under the MIT license.

What you can do with Butterfish Shell

• Prompt the AI from the shell by starting commands with a capital letter to get contextual help, command suggestions, or code modifications.
• Ask questions like “Why did that command fail?” and receive explanations with shell history in context.
• Use Goal Mode to have an agent propose and execute commands to reach a goal (with guarded and unsafe variants).
• Autosuggest shell commands as you type, with context from recent history.
• Customize prompts and models, switch between OpenAI-compatible endpoints, and view raw prompts/responses in verbose mode.
• Access a suite of CLI tools for prompting, summarizing, generating commands, and managing embeddings of local files.
• Use a Neovim plugin butterfish.nvim to enable LLM prompting inside Neovim.
• Store authentication tokens and prompt configurations locally for privacy and portability.

How Butterfish Shell Works

• Architecture: Butterfish starts a new shell process, intercepts input/output, and buffers history in memory. When a capital-letter command is entered, it forwards the prompt to the OpenAI API and streams the assistant’s response back to the terminal. Autosuggest and prompt history leverage this shared context.
• History model for API requests: System Message (configurable prompts), User Messages (commands, shell output, prompts), Assistant Messages (previous AI responses). The AI request history is capped by token limits.
• Shell integration: Butterfish modifies the shell prompt to show usage status (e.g., added emoji), but otherwise remains non-intrusive to standard shell operations.

Installation & Authentication

• macOS/Linux: Install via Homebrew: brew install bakks/bakks/butterfish (for the shell wrapper) or install with go install github.com/bakks/butterfish/cmd/butterfish@latest.
• First run prompts for an OpenAI API key and stores it in ~/.config/butterfish/butterfish.env as OPENAI_TOKEN=sk-....
• Optional: alias butterfish to bf for convenience.
• Configuration files: prompts.yaml in ~/.config/butterfish/ to customize system/user prompts and behaviors.

Usage Overview

• Start the Butterfish shell wrapper: butterfish shell (wraps your current shell).
• Normal commands: ls -l executes as usual.
• AI prompts: Start with a capital letter to query the AI, e.g., How do I recursively find local .py files?
• Autosuggest: Press Tab to accept suggested commands.
• Goal Mode: Prefix a command with ! to have the AI act as an agent; prefix with !! to run in unsafe mode.
• Special commands: Help, Status, History, etc.
• Other commands: plugin, prompt, summarize, gencmd, exec, index, clearindex, loadindex, showindex, indexsearch, indexquestion.

Safety & Costs

• OpenAI API usage may incur costs. Autosuggest is typically the most expensive feature. You can reduce spend by disabling autosuggest or adjusting timeouts.
• Goal Mode can automate actions; use with caution and be mindful of potential destructive commands.

Core Features

• Shell wrapper that enables AI prompting directly in the terminal by starting commands with a capital letter.
• Contextual AI prompts that include shell history for high-context responses.
• Autosuggest for command completions based on recent history and typing input.
• Goal Mode (normal and unsafe) to let an AI agent execute commands to achieve goals.
• Transparent prompts with configurable prompts.yaml for customization.
• Support for multiple models and OpenAI-compatible endpoints via --base-url.
• Neovim plugin (butterfish.nvim) for prompting inside Neovim.
• Additional CLI utilities for summarizing, generating commands, and managing embeddings of local files.
• Persistent local storage of API tokens and prompt configurations for privacy.