butterfish

butterfish is a revolutionary open-source tool designed for developers, system administrators, and anyone who lives in the command line. It functions as an intelligent shell wrapper for bash and zsh, seamlessly integrating the power of Large Language Models (LLMs) like OpenAI's GPT series directly into your terminal workflow. Often described as "GitHub Copilot for the shell," butterfish enhances your command-line experience by providing contextual AI assistance, command generation, and automation, all without ever leaving your terminal.

The core concept of butterfish is its intuitive and unobtrusive integration. You continue to use your shell as you normally would, but with an added superpower: simply start any command with a capital letter to turn it into a prompt for the AI. The AI has access to your recent shell history, allowing it to understand the context of your work. This enables you to ask follow-up questions, debug failed commands, and receive suggestions that are highly relevant to your current task, eliminating the tedious cycle of copying and pasting errors into a search engine.

How to use butterfish

Getting started with butterfish is straightforward. It's designed for macOS and Linux environments.

1. Installation: You can install butterfish easily using Homebrew on macOS (brew install bakks/bakks/butterfish) or with Go (go install github.com/bakks/butterfish/cmd/butterfish@latest).
2. Authentication: On the first run, butterfish will prompt you for an OpenAI API key. You need to generate a key from your OpenAI account and paste it in. The key is stored locally in ~/.config/butterfish/butterfish.env.
3. Running the Shell: Launch the AI-powered shell by running the command butterfish shell. It's recommended to create an alias like alias bf="butterfish" in your .zshrc or .bashrc for quicker access.
4. Prompting the AI: Inside the butterfish shell, type a prompt starting with a capital letter, for example: Give me a command to find all .log files larger than 100MB. The AI will respond with the appropriate command.
5. Debugging: If a command fails, you can immediately ask for help: Why did that command fail? The AI will analyze the error message and your command in context and provide an explanation and a corrected version.
6. Using Goal Mode: For more complex tasks, you can activate Goal Mode by starting a prompt with !. For example: !Install python dependencies for this project and run the tests. The AI will act as an agent, suggesting commands one by one for you to execute. Use !! for an unsafe mode where it executes commands without confirmation (use with caution).
7. Autosuggest: As you type, butterfish will proactively suggest command completions, which you can accept by pressing the Tab key.

Core Features of butterfish

• Context-Aware AI Assistance: butterfish maintains a history of your commands and their outputs, allowing the AI to provide contextually relevant answers and debugging help.
• Seamless Shell Integration: It wraps your existing shell (bash or zsh) without interfering with your custom configurations, aliases, or functions.
• AI Command Generation & Autosuggest: Generate complex shell commands from natural language descriptions and get intelligent, Copilot-style suggestions as you type.
• Autonomous Agent (Goal Mode): A powerful feature where the AI can execute a series of commands to achieve a complex goal, with modes for both user-confirmed and autonomous execution.
• Full Customization and Transparency: Users can view and edit the system prompts sent to the AI, select different LLM models (including local ones via compatible APIs), and inspect raw API requests in verbose mode.
• Built-in Utilities: Includes additional CLI tools for summarizing text files, generating commands (`gencmd`), and managing semantic embeddings of local files for code-aware Q&A (`index`, `indexsearch`).
• Neovim Integration: A dedicated `butterfish.nvim` plugin brings the same fluent LLM prompting capabilities directly into the Neovim editor for tasks like refactoring code.
• Open Source: Licensed under the MIT license, butterfish is free to use, modify, and contribute to, fostering a transparent and community-driven development process.

Use Cases for butterfish

butterfish is versatile and can be applied in numerous scenarios:

• Learning & Exploration: Newcomers to the command line can learn complex tools like awk, sed, or `ffmpeg` by describing what they want to do in plain English.
• Efficient Debugging: Instead of searching for cryptic error messages online, developers can instantly get an explanation and a fix, dramatically speeding up the development cycle.
• Complex Command Crafting: For one-off tasks that require a complicated chain of commands, like finding, processing, and moving files based on specific criteria, butterfish can generate the command in seconds.
• Project Scaffolding & Automation: Use Goal Mode to automate setup tasks, such as cloning a repository, installing dependencies from a `package.json` or `requirements.txt`, and running initial build commands.
• Codebase Q&A: By indexing a project's source code with the `index` command, a developer can ask questions like indexquestion Where is the database connection string defined? to quickly navigate and understand unfamiliar code.

Advantages of butterfish

The primary advantage of butterfish is the significant boost in productivity and efficiency it offers. By integrating AI directly into the terminal, it eliminates context switching and streamlines workflows. It empowers both novice and expert users, making the command line more accessible and powerful. Its commitment to transparency and customization allows users to tailor the tool to their specific needs and trust its operations. Finally, being open-source ensures it remains a free, community-supported tool that evolves with user feedback.

Pricing and Plans

butterfish itself is a completely free and open-source tool, available under the MIT License. There are no subscription fees or charges for using the software. However, to function, butterfish requires an API key for an LLM provider, with OpenAI being the default. Users are responsible for the costs associated with their own API usage. The cost depends on the model chosen and the frequency of use (e.g., autosuggest is more API-intensive). The tool provides options to manage costs, such as adjusting autosuggest timeouts, disabling it, or using more cost-effective models.