Butterfish

A one-sentence summary

Butterfish is an open-source Shell wrapper that adds AI-powered Q&A, command generation, autocompletion, and Agent execution capabilities to bash and zsh, allowing users to obtain context-related assistance without having to copy terminal output.

The software itself is available free of charge under the MIT license, but it requires the user to have their own OpenAI API key; the tokens generated by calling the models as well as the costs associated with the service layer are the responsibility of the user.

What is Butterfish?

Butterfish Shell is maintained by Peter Bakkum, and it is intended for developers and system administrators who work regularly in macOS or Linux terminals. It does not replace the system’s shell; instead, it launches an additional session on top of the existing bash or zsh shell and captures input and output.

Regular commands are still executed by the Shell, while natural language inputs that start with uppercase letters are sent to the model. Butterfish takes into account recent commands, outputs, and previous conversations as part of the context, which allows one to ask why a previous command failed.

Current maintenance status

As of August 20, 2026, the latest version available on the official GitHub is v0.4.3; the release notes mention fixes related to Agent input processing, Shell startup prompts, and low-latency auto-completion. The Go module page also lists v0.4.3 and specifies that it is licensed under the MIT license.

The project is still in the 0.x version, so it is not possible to assume compatibility based on the stable 1.0 interface. Before upgrading, it is necessary to read the changes, retain any custom configuration settings, and test shell interactions as well as model parameters in a non-critical environment.

Main functions

Contextual terminal Q&A

In Butterfish Shell, you can ask questions of the model by starting your input with uppercase letters. Recent inputs, outputs, and AI responses are kept in context, which makes it convenient to explain errors, ask follow-up questions, and get suggestions for the next steps based on the current directory.

Automatic command completion

When a user enters a command, Butterfish can predict the complete command based on the Shell history and previous AI suggestions, allowing the user to accept it using Tab. This automatic completion feature sends frequent requests to the model, which can lead to increased costs as well as the risk of sensitive information being transmitted to the model service.

Agent Mode

Starting a task with a single exclamation mark enters Agent Mode, allowing the model to issue and execute commands repeatedly based on the goals set, and to adjust its strategies accordingly. The current safety mode retains the step of manual confirmation, whereas using two exclamation marks activates a risky mode in which actions are carried out without any confirmation.

Action Mode

Starting a request with a single @ will instruct the model to generate exactly one Shell command, which is then displayed in the terminal for the user to review. Using two @ will execute the generated result immediately; this approach should be considered only when the target, directory, and any side effects are clearly defined.

Independent prompt command

The prompt subcommand can be used to send text directly, or it can combine input from a pipeline with a prompt in order to obtain model results in a streaming manner. It is suitable for explaining configurations, summarizing text, or handling one-time queries outside of scripts.

Generated by the gencmd command

gencmd converts natural language into Shell commands and allows users to check the results first. The forced option skips confirmation and executes the generation command directly, which carries a high risk when it comes to deletion, overwriting, network downloads, and permission changes.

Fix for exec errors

exec is used to run a specified command; in the event of failure, it requests model analysis and suggests fixes. It can reduce the steps needed to copy error logs, but the suggestions still need to be manually verified taking into account the operating system, tool version, and project status.

• Perform AI Q&A with Shell history context directly in the terminal.
• Provide Tab auto-completion based on the current input and recent commands.
• Convert natural language into verifiable Shell commands.
• Run the command and generate repair suggestions based on the error output.
• Use Agent Mode to iteratively execute and debug multi-step tasks.
• Use Action Mode to generate a command suitable for the current task.
• View and edit the system messages and command prompts sent to the model.
• Model services that enable connection to OpenAI or support the Responses streaming interface.
• Files or the output of other commands are sent to the model for processing via standard input.

How does the Shell mode work?

1. When the user starts Butterfish Shell, the program launches the original bash or zsh within its wrapper layer.
2. Normal keyboard input and command output continue to be displayed in the terminal and written to the memory history.
3. Regular commands are sent directly to the Shell, while uppercase prompts and special mode prefixes are intercepted by Butterfish.
4. When a model request is initiated, the program constructs the context from system information, prompt templates, and recent history.
5. The request is sent via the OpenAI Responses interface or a compatible server, and the results are written back to the terminal in a streaming manner.
6. If the model suggests a command, safe mode first places that command in the Shell for the user to review and edit.
7. The user can proceed, ask further questions, or exit; the history of the current session is truncated and organized within the context window.

The memory history does not mean that the data never leaves the device; whenever an AI request is made, the commands selected for the context, the outputs, prompts, and system information are sent to the configured model server.

Installation guide

Install via Homebrew

MacOS users can use the Homebrew Tap provided by the maintainers to carry out the installation, after which they can start the Butterfish Shell. Once the installation is complete, it is advisable to check the version and the help documentation to ensure that the correct binary file is being used.

1. Confirm that the device runs a supported version of macOS and that Homebrew is installed.
2. Install Butterfish from the maintainer’s Tap; do not use software packages with the same name from unknown sources.
3. Run the version command and compare it with the latest official release.
4. When starting Shell mode for the first time, configure the model API key as prompted.
5. Run ordinary commands and simple question-answers in the temporary directory to verify that there are no abnormalities in Shell input and output.
6. It is confirmed that safe mode will wait for manual verification before executing the generation command.

Install via Go

macOS and Linux also allow the use of the Go toolchain to install the latest modules, making them suitable for users who do not use Homebrew or those who wish to build from source. The binaries installed in this way are usually located in the bin directory of the Go environment, and it is necessary to ensure that this directory is included in the PATH.

1. Install the currently available Go toolchain and verify the Go environment directory.
2. Install the latest Butterfish commands using the official module path.
3. Add the Go bin directory to PATH and reopen the terminal.
4. Check the Butterfish version, license, and help output.
5. Configure the key during the first startup, and test the connection using tests that do not cause any side effects.

First-time configuration and API key

On the first invocation, Butterfish will ask for an OpenAI API key, which is then saved in an environment file located in the user’s configuration directory. This key is not related to a ChatGPT web subscription; whether there is a balance and access rights depend on the individual API account.

• Use only project keys whose permissions and quotas are restricted; do not reuse production keys with high permissions.
• Restrict the system permissions on the configuration directories and key files to prevent other local users from accessing them.
• Do not submit the configuration directory to Git, sync it to public cloud storage, or include it in issue reports.
• Once a key is found in logs, screenshots, or shared terminals, it should be revoked immediately and replaced.
• When connecting to a compatible server, it is confirmed that the key is sent to that server along with the request.
• Each team’s equipment should be assigned its own key and budget, in order to enable auditing and to prevent abnormal usage.

Daily use tutorial

1. Enter the project directory and start Butterfish Shell; first, use regular commands to check the current status.
2. When an error occurs, ask in plain language using uppercase to find out the reason, and request that the model provide an explanation rather than fixing it immediately.
3. Check for differences in the commands referenced in the answers, paths, tool versions, and operating systems.
4. Use Safe Action Mode when a command is needed, so that the result is first sent to the terminal rather than being executed directly.
5. For complex tasks, Agent Mode can be used, but the commands and outputs must be reviewed each time.
6. After completion, check whether sensitive logs have been generated, then exit the wrapper shell.

Safe usage of Agents and Actions

Automatic execution mode can delete files, overwrite data, upload secrets, install malware, or change system permissions. Even if a task seems simple, it should not be enabled on production servers, in administrator shells, or in directories containing unbacked up data.

• Run a read-only check first, and then consider write, install, move, or delete operations.
• Use regular users, containers, temporary branches, or one-time virtual environments to limit the scope of impact.
• Expand variables, wildcards, recursive targets, and the current working directory before execution.
• Manual confirmation is required for downloading and executing scripts, gaining elevated privileges, and running disk commands.
• Make important changes by first submitting them to version control or by creating verifiable backups.
• Do not treat the model’s responses as commands for security audits or access authorization.

Model selection and local models

The current documentation for the main GitHub branch lists Shell and prompt as default models of GPT-5.5, with a high level of inference intensity; the fast mode also makes use of the priority service layer provided by the Responses API. Users can override the model, inference intensity, maximum output amount, and service layer using specific parameters.

The older pages on the official website still show examples of GPT-4 Turbo and GPT-3.5 Turbo; these are historical documents. The actual default values should be based on the help information provided by the installed version as well as the current repository, since the model names and their availability can change depending on the API platform used.

Butterfish can also connect to local or remote servers that provide an OpenAI-compatible streaming interface for generating responses. Compatibility requires not only similar path structures but also the proper handling of streaming results; the prompt templates are optimized for OpenAI, so the performance of local models may differ significantly.

Price and usage costs

The Butterfish program is free of charge; there are no official membership plans, monthly fees, or costs based on the number of seats. The MIT license permits use, modification, and distribution under certain conditions, and the actual costs for users stem mainly from the model APIs, priority service levels, local computing resources, and maintenance.

Once automatic completion is enabled, the model may be requested frequently during pauses, and this represents one of the main sources of usage. It is possible to disable automatic completion or increase the waiting time before a request is sent, as well as to eliminate any unnecessary priority service layers.

Tips for transparency and customization

Butterfish stores system prompts, command generation rules, and auto-completion suggestions in YAML configuration files, which users can view and edit. When making changes, the auto-replacement option should be turned off; otherwise, updating the prompt library might overwrite the custom versions.

• Check whether the Shell system prompts are in line with the team’s security standards and command conventions.
• The command is required to generate default interpretation parameters, paths, and side effects.
• Set clear rules to prohibit automatic execution for production, database, and cloud resources.
• After the upgrade, there will be changes in the default prompts; do not blindly retain outdated templates.
• Use version control to save the masked prompt files, excluding keys and local paths.
• It should be noted that warning rules can only reduce the likelihood of errors; they cannot replace operating system permissions or manual approval processes.

Privacy and data security

Butterfish is a local, open-source CLI; it does not have a centralized Butterfish account nor any service for storing chat history. Model requests still send the selected shell history, command outputs, system information, user prompts, and AI conversations to the configured API endpoint.

When detailed mode is used, the entire request and response may be printed to the terminal or written to logs in the system’s temporary directory. The output on the terminal often includes access tokens, environment variables, database contents, and customer information; debugging logs should be treated as sensitive files.

• Do not initiate contextual Q&A immediately after displaying keys, production database records, or customer information.
• Clean up Butterfish logs and Shell output before sharing terminals, recording screens, or reporting issues.
• When connecting to third-party or locally compatible endpoints, verify their logging, training, and retention policies.
• Limiting the historical window does not guarantee that secrets will be excluded; it is necessary to actively avoid outputting them during sessions.
• Remote servers should use encrypted transmission; do not send authentication tokens to untrusted addresses.
• In a corporate environment, it is first necessary to establish policies regarding the use of code, data, and model providers.

Support systems and dependencies

Which users are it suitable for

• Command-line beginners: They can understand what commands do and why errors occur, but they still need to learn the basics of Shell.
• Software developer: Continue to ask questions based on the current directory, build output, and test failures.
• DevOps engineer: Generates read-only diagnostic commands and analyzes logs; production changes still require approval.
• Open-source enthusiasts: Reviewing source code, template suggestions, and data transmission logic.
• Local model user: Connect the terminal assistant to a local service that is compatible with the Responses interface.
• Teams that need customizable prompts: Include the command style and security requirements in a transparent prompt database.

Typical use cases

• Explain the recently failed build, test, package management, or Git command.
• Generate read-only commands for searching for files, viewing ports, counting directories, and filtering logs.
• Pass the configuration file or command output to the model summary via a pipe.
• Adjust the parameters according to differences in tool versions, and explain the function of each flag.
• Run tests in the temporary branch and try to fix simple issues using the Agent.
• Use local models to handle low-risk internal tasks that are not suitable for being sent to a public cloud.

Product advantages

• Leverage the Shell history directly to reduce copy commands, errors, and back-and-forth of context.
• It includes the existing bash or zsh; ordinary command usage remains largely unchanged.
• Q&A, single-command, and multi-step Agents have distinct input prefixes.
• The prompt templates and the original model requests can be viewed and modified.
• It supports OpenAI’s default services, as well as connection to compatible local or remote models.
• MIT is open-source and there are no subscription fees for Butterfish; its source code and behavior can be reviewed.
• The prompt, gencmd, and exec subcommands can be used independently of the full Shell mode.

Usage restrictions and precautions

• Currently, the official version supports macOS as well as bash and zsh on Linux; there is no native support for Windows.
• The dual-prefix mode for Agents and Actions skips confirmation, and incorrect commands can lead to irreversible losses.
• The model may generate invalid commands based on an incorrect version of the tool, operating system, or path.
• The history and output of Shell become part of the model’s context, posing a risk of leakage of sensitive and business-related data.
• Automatic completion of frequent API calls can result in unexpected costs related to tokens and priority levels.
• Local-compatible servers must implement the Responses streaming interface; ordinary Chat Completions compatibility may not be sufficient.
• The 0.x version of the project may still see changes to parameters, default models, interaction methods, and prompt formats.
• Butterfish is not a system for permission isolation, backup, auditing, malware protection, or formal operational approval processes.

APIs, GitHub, and open source status

The complete source code for Butterfish is hosted on a public GitHub repository; it is written in Go and licensed under the MIT license. The repository includes the command entry point, Shell wrappers, prompts, testing tools, deployment configurations, and dependency information, allowing developers to review, modify, and distribute it in accordance with the license terms.

It is not a SaaS service that provides remote business APIs; rather, it is a client for the OpenAI Responses API. The project is not the model itself either – the MIT license applies only to the Butterfish code, and it does not cover OpenAI, third-party models, user data, or other licenses that are required.

Basic information

Recommendation score

Its rating is 4.3 out of 5 points. Butterfish integrates Shell history, transparent prompts, single-command as well as multi-step agents into the familiar terminal environment; it is open-source, lightweight, and allows connection to local models, making it very attractive to users who rely heavily on the command line.

The deductions are mainly caused by the high risks associated with automatic execution, privacy issues related to the terminal environment, costs related to API usage, and the limited scope of platform support. It is better suited to serve as an auxiliary tool for experienced users, rather than allowing those who are not familiar with Shell to execute model commands without any oversight.

Frequently Asked Questions

Is Butterfish free?

The software itself is free and is licensed under the MIT license; there are no official subscription plans. When using OpenAI or other cloud services, one must pay the corresponding API fees themselves.

Is Butterfish related to fish shell?

There is no direct connection; Butterfish is merely the name of the product. The official tests currently focus on bash and zsh, and it should not be assumed that it is compatible with the fish shell just because the name includes “fish”.

Is it compatible with Windows?

The official installation instructions currently list only macOS and Linux; there is no commitment to support for Windows natively. It is necessary to test whether WSL is suitable by using specific shells, terminals, and model configurations.

Is a ChatGPT subscription required?

There is no need for a ChatGPT web subscription, but by default an individual OpenAI API key along with a sufficient balance is required. Web memberships and API billing are separate products.

Which model is used by default?

The current main branch on GitHub uses GPT-5.5 along with a high level of inference intensity by default; the quick mode makes use of the priority service layer. The old website still provides examples using GPT-4 Turbo, but it is advisable to consult the documentation related to the installed version for accurate information.

Can local models be used?

It is possible to connect to a local server that provides an API of the stream-based type compatible with OpenAI. Services that are only compatible with traditional chat interfaces may not function, and the quality of the models used might be lower than that of the models intended for use with default prompts.

Is Shell’s history sent to the cloud?

When an AI request is sent, Butterfish sends the selected recent commands, outputs, and conversations as context to the configured model endpoint. Sensitive outputs should not be included in the session that is prepared for transmission.

Is Agent Mode safe?

In the single exclamation mark mode, it is still necessary to carefully examine the model commands; the double exclamation mark option skips the confirmation step, which carries a very high level of risk. It is recommended to use the safe mode only in isolated environments or for temporary tasks that have backups.

What is the difference between Action Mode and Agent Mode?

In Action Mode, only one Shell command is attempted to be generated and then the process ends; in Agent Mode, multiple steps can be carried out, the results can be observed, and strategies can be adjusted. With a single prefix, checking is performed by default, while with two prefixes, execution takes place automatically.

Why can auto-completion be expensive?

It will initiate model predictions whenever the user stops typing; frequent requests can result in an accumulation of tokens and additional costs related to the service layer. It is possible to turn off automatic completion, increase the waiting time, or choose a cheaper model.

Can I see the full instructions?

It is possible to edit the local YAML prompt library, and the original requests and responses can be viewed in detailed mode. Detailed logs may contain sensitive information, so they need to be properly deleted after use.

Is Butterfish completely offline?

By default, it is not the case; instead, it connects to the OpenAI API. Only when a local-compatible model is configured and it is ensured that all requests are directed to local endpoints can the model interactions take place on the local machine or within a private network.