Butterfish: a shell wrapper that turns capital letters into AI prompts

The interaction model: a capital letter

Butterfish is for people who work from the command line, and it adds AI prompting to your shell, bash or zsh, with OpenAI. The framing given is to think of it as GitHub Copilot for the shell.

The mechanism is a single convention, and it is the part worth understanding. You use your shell as normal, and you start a command with a capital letter to prompt the AI. A normal lowercase command runs as it always did. A capitalised one is sent to the model instead.

The reason this works is stated plainly: the AI sees the shell history, so you can ask contextual questions like why did that command fail. And the README's description of the experience is that this is a pattern where you get high-context help exactly when you want it, with no copying and pasting.

That last point is the whole design. The alternative is to copy an error message into a chat window, paste it, and describe what you were doing. Because the wrapper is sitting between you and the shell, it already has the command you ran and its output, so the prompt is automatically contextual. If you ran a command that failed, the model can see the command and the error. If you printed a file with cat, the model can see that too.

Shell mode wraps your shell rather than replacing it, and it is tested with zsh and bash. You can autocomplete commands and prompt questions with Tab, and prompts and autocomplete use local context for answers, like ChatGPT.

The primary language is Go, the licence is MIT, the default branch is main, and the homepage is butterfi.sh. The recent releases are v0.4.3 from 2026-06-03, v0.4.2 from 2026-05-28 and v0.4.1 from 2026-05-27, and the last push was on 2026-06-03 with the project not archived. There is also a separate Butterfish Neovim plugin, so the same idea is being applied to another terminal workflow.

The five modes, and the two you should be careful with

The shell mode command reference is the most useful documentation in the project, because it spells out exactly what each prefix does and what the trade-offs are.

Use:
  - Type a normal command, like 'ls -l' and press enter to execute it
  - Start a command with a capital letter to send it to GPT, like 'How do I
    recursively find local .py files?'
  - Autosuggest will print command completions, press tab to fill them in
  - GPT will be able to see your shell history, so you can ask contextual
    questions like 'why didnt my last command work?'
  - Start a command with ! to enter Agent Mode, in which GPT will act as an agent
    attempting to accomplish your goal by executing commands, for example '!Run
    make in this directory and debug any problems'.
  - Start a command with !! to enter Unsafe Agent Mode, in which GPT will execute
    commands without confirmation. USE WITH CAUTION.
  - Start a command with @ to enter Action Mode, in which GPT will attempt
    exactly one shell command for your request or decline if a single command
    is not a good fit.
  - Start a command with @@ to auto-execute the Action Mode command
    immediately. USE WITH CAUTION.

The escalation ladder is the interesting part. A plain command executes. A capitalised command asks the model a question. A single exclamation mark enters Agent Mode, in which the model attempts to accomplish your goal by executing commands, for example running make in a directory and debugging any problems. A double exclamation mark enters Unsafe Agent Mode, in which the model executes commands without confirmation, and the help text says to use it with caution.

Then the at signs. A single at sign enters Action Mode, in which the model attempts exactly one shell command for your request or declines if a single command is not a good fit. A double at sign auto-executes that Action Mode command immediately, again with the caution note.

So there are four distinct levels of permission and the two middle ones are the design's best idea. Agent Mode asks for confirmation between commands, which is what you want for a multi-step task, and Action Mode is a deliberately constrained step where the model either produces one command or says it cannot be done as one command. That is a much better default for a terminal than unrestricted execution, because it keeps the model in the role of suggesting while you stay in the role of deciding.

There are also three special commands, which are a nice touch because they answer the question you would otherwise be unsure about:

  - Help : Give hints about usage.
  - Status : Show the current Butterfish configuration.
  - History : Print out the history that would be sent in a GPT prompt.

History in particular is the one to know about. It prints the history that would be sent in a GPT prompt, which means you can see exactly what context the model is being given before you send it.

The help text is also candid about cost. If you do not have OpenAI free credits then you will need a subscription and you will need to pay for OpenAI API use, and autosuggest will probably be the most expensive feature. You can reduce spend by disabling shell autosuggest with -A or by increasing the autosuggest timeout, for example -t 2000.

That is a useful piece of advice, because autosuggest fires on every keystroke in a shell and is therefore the highest-frequency call the system makes.

Installation, the API key, and where the key lives

Butterfish works on macOS and Linux, and the install route is Homebrew on macOS:

brew install bakks/bakks/butterfish
butterfish shell
Is this thing working? # Type this literally into the CLI

The test string at the end is a nice touch, because it tells you how to confirm the thing works without needing a real prompt.

The alternative is a Go install:

go install github.com/bakks/butterfish/cmd/butterfish@latest
$(go env GOPATH)/bin/butterfish shell
Is this thing working? # Type this literally into the CLI

The command path uses the go env GOPATH lookup, which is the standard way to reach a binary installed with go install when your shell has not been told about the Go bin directory.

The first invocation prompts you to paste in an OpenAI API secret key, and the key is then written to a file at ~/.config/butterfish/butterfish.env, which looks like this:

OPENAI_TOKEN=sk-foobar

That is worth thinking about for a moment. The key is a plain environment file in your home directory, and it holds a live API credential that can be billed. Whether it is created with restrictive permissions is not something the README states, so if you are the kind of person who checks, check.

The shell also suggests aliasing the command to something shorter, so that you can run it with only bf:

alias bf="butterfish"

A separate Neovim plugin exists for the same idea in another terminal workflow, which suggests the author treats the shell wrapper as one instance of a pattern rather than the whole project.

For the model configuration, shell mode defaults to using gpt-5.5 with high reasoning effort and the Responses API priority service tier for fast mode, and you can override the model with a flag:

butterfish shell -m gpt-5.5

The default being a high reasoning effort model is a deliberate choice and it costs money on every prompt. Combined with the note that autosuggest is the most expensive feature, the shape of the cost profile is clear: a capitalised question is one expensive call, and an autosuggest keystroke is an expensive call too, and there are many more of the second kind than the first.

Prompt transparency, and the repository layout

The Prompt Transparency section is the one that distinguishes this from most AI-enabled command line tools, and it is worth reading in full.

Many AI-enabled products obscure the prompt, meaning the instructional text sent to the AI model. Butterfish makes it transparent and configurable. To see the raw AI requests and responses you can run the tool in verbose mode with butterfish shell -v and watch the log file, which is at /var/tmp/butterfish.log on macOS, and for more verbosity you use -vv. And to configure the prompts you can edit ~/.config/butterfish/prompts.yaml.

So the instruction text that drives the model is a YAML file on your disk, and the traffic is inspectable. That is a real property rather than a feature bullet, because a prompt-driven tool that keeps its prompt secret is asking for trust it has not earned, and one where the prompt is a file you can edit is asking you to read it. The verbose output screenshot in the README is showing exactly that.

The repository layout shows how the pieces are arranged. There is cmd/ for the command line entry point, butterfish/ for the main implementation, bubbles/ for the terminal UI, prompt/ for the prompt definitions, util/ for helpers, perf/ for performance work, bin/ for scripts, assets/ for images, and vhs/ for the demo recordings. There is a Makefile, a.goreleaser.yml for release builds, a Brewfile, an AGENTS.md, and a go.mod at the root.

The go.mod is worth reading because it shows the stack. The OpenAI Go SDK at version 3.17.0 is the model client, and alecthomas/kong is the command line parser, which is a pleasant structured alternative to the standard library's flag package and explains the nicely formatted help output. alecthomas/chroma is the syntax highlighter, and charmbracelet/lipgloss is the styling library, both of which are what you would reach for to make a terminal program look like it belongs in a modern terminal. creack/pty is a pseudo-terminal implementation, and it is there because the tool has to drive an interactive shell, which requires a pty rather than pipes. mitchellh/go-homedir and joho/godotenv handle the home directory lookup and the environment file. mattn/go-runewidth is a text width calculation, needed to lay out a table of terminal output. And bakks/tiktoken-go is a tokenizer, a fork in the same namespace, which is how the tool counts tokens for the autosuggest budget.

That last one is a good clue about the design. Counting tokens locally before sending a request is what lets the tool decide whether a long shell history fits in the context window, and it is a thing you cannot do well by guessing.

How to evaluate it, and the questions to ask first

There are four things to consider, and the first is the security model, which the README is upfront about.

The prefix ladder ends with two modes that execute without confirmation, and the help text marks both with a caution note. Unsafe Agent Mode is the model running commands with no confirmation, and the double at sign auto-executes an Action Mode command immediately. If you are working on a machine with anything valuable on it, the sensible arrangement is to use Agent Mode, which confirms each command, and to leave the double-prefix modes alone. The existence of the two unsafe modes is not a design flaw, but they are opt-in for a reason and the caution is there for a reason.

Second, the cost. Every capitalised prompt is a model call at a high reasoning effort, and autosuggest is called often enough that the README singles it out as the most expensive feature and gives you two ways to reduce it, disabling it with -A or raising the timeout with a flag. If you adopt this on a work machine, the bill is part of the feature and you should decide in advance which of the four modes you are willing to leave enabled.

Third, what the model can see. The whole premise is that the model gets your shell history, and that history contains whatever you have done, which for some people includes credentials in an environment variable, a path that reveals a home directory name, or the contents of a file you printed. The History command exists so you can see exactly what would be sent, and it is worth using it before you ask anything sensitive. The prompt file being editable and the verbose log existing both help here, and both are the reason to trust the tool with a real machine.

Fourth, the shell coverage. It is tested with zsh and bash, and it works on macOS and Linux. There is no Windows support mentioned, and if your shell is fish or zsh with a non-standard prompt setup, the wrapping may not behave. The pty dependency means it is driving a real terminal, so a shell with unusual terminal handling is where you would expect friction.

What you get is a small, focused tool that solves the copy-paste problem in a way nothing else has: the context is already there. It is MIT licensed, the code is Go, the prompts are yours to read and change, and the model is swappable. The version is 0.4.3, so the command line interface is still apt to change, and the last push was on 2026-06-03, so the project is quiet rather than abandoned.

Editorial conclusion

Adopt Butterfish if you live in the terminal and find yourself pasting errors into a chat window, since the wrapper already has the command and its output, which removes the copy and paste step entirely. Do not adopt it on a machine with credentials in your history without reading what gets sent, because the entire premise is that the model sees your shell history, and do not leave Unsafe Agent Mode or the double at sign auto-execution enabled on a work machine. Before you commit, read the prompts file at ~/.config/butterfish/prompts.yaml, run the History command to see the context that would be transmitted, and set the autosuggest timeout or disable autosuggest entirely, since it is the most expensive feature and it fires on every keystroke.

Frequently asked questions

Official sources

1. bakks/butterfish on GitHub
2. License: MIT
3. Project website
4. README
5. Releases