Butterfish CLI Tools

Description

Butterfish is a suite of command-line interface (CLI) tools designed to enhance productivity for software engineers and command-line users by integrating Large Language Models (LLMs) directly into their workflow. The core offering, Butterfish Shell, transforms your existing shell (bash, zsh) into an AI-powered assistant. By simply starting a command with a capital letter, users can prompt the AI with contextual questions, leveraging shell history for relevant assistance without the need for copy-pasting.

This tool acts as a "shell wrapper," intercepting input and output to provide AI capabilities. Users can ask for commands, inquire about command failures, or even use "Goal Mode" (initiated with '!') where the AI acts as an agent to execute commands and achieve a specified goal, with an "Unsafe Goal Mode" (initiated with '!!') for automated execution. Butterfish Shell offers features like command autocompletion, similar to GitHub Copilot, and maintains conversation history, allowing for iterative refinement of AI-generated commands or responses.

Beyond the shell integration, Butterfish includes other utilities such as a direct prompt client, a command generator, a file summarizer, and tools for managing embeddings of local files. The project emphasizes transparency, allowing users to view and customize the prompts sent to the AI via configuration files. It supports OpenAI-compatible APIs, enabling the use of local or alternative LLM providers. Butterfish is open-source, licensed under the MIT license, and welcomes community contributions.

The target audience includes developers, system administrators, and anyone who frequently works from the command line and seeks to leverage AI for faster task completion, debugging, and code generation. The value proposition lies in its seamless integration into existing workflows, reducing context switching and providing high-context AI assistance precisely when and where it's needed.

Butterfish CLI Tools's Core Features

• AI-powered shell integration for bash and zsh

• Contextual AI prompting using shell history

• GitHub Copilot-style command autocompletion

• Goal Mode for AI-driven command execution

• Unsafe Goal Mode for automated command execution

• Customizable AI prompts and system messages

• Support for OpenAI-compatible APIs and local models

• File summarization and text embedding capabilities

• Transparent logging of AI requests and responses

• Open-source under the MIT license

How to use Butterfish CLI Tools?

1. 1

   Install: Use Homebrew on macOS (`brew install bakks/bakks/butterfish`) or `go install`.

2. 2

   Authenticate: Run `butterfish shell` and paste your OpenAI API secret key when prompted.

3. 3

   Configure: Optionally, alias `butterfish` to `bf` in your shell's rc file for convenience.

4. 4

   Use Shell Mode: Start commands with a capital letter for AI prompts or '!' for Goal Mode.

5. 5

   Autosuggest: Press Tab to accept AI-suggested command completions.

6. 6

   Debug: Ask contextual questions like 'Why did that command fail?'

7. 7

   Summarize: Use `butterfish summarize <files>` to get semantic summaries of files.

Butterfish CLI Tools's Use Cases

• AI Shell Assistant
• Command Generation
• File Summarization
• Code Debugging
• Contextual Prompting
• Agentic Task Execution
• Local LLM Integration
• Text Embedding Management

FAQ from Butterfish CLI Tools

• What is Butterfish and what does it do?

  Butterfish is a set of CLI tools that integrate AI prompting into your command-line workflow, offering features like AI-assisted shell commands, autocompletion, and goal-oriented task execution.

• How does Butterfish Shell add AI superpowers to my terminal?

  Butterfish Shell wraps your existing shell (bash, zsh) and allows you to prompt the AI by starting commands with a capital letter. It uses your shell history to provide contextual AI assistance.

• Can Butterfish help me debug commands?

  Yes, you can ask contextual questions like 'Why did that command fail?' after a command has executed, and Butterfish will use the AI to help diagnose the issue.

• What is Goal Mode in Butterfish?

  Goal Mode, initiated with '!', allows the AI to act as an agent. You provide a goal, and the AI will suggest and execute commands to achieve it, using your shell history for context.

• How do I install Butterfish?

  Butterfish can be installed on macOS and Linux. On macOS, you can use Homebrew (`brew install bakks/bakks/butterfish`). Alternatively, you can use `go install`.

• Does Butterfish require an OpenAI API key?

  Yes, Butterfish uses OpenAI APIs by default. You will need to provide your OpenAI API secret key during the first invocation of `butterfish shell`.

• Can I use Butterfish with local LLMs or other API providers?

  Yes, Butterfish supports OpenAI-compatible APIs. You can use the `--base-url` flag to point to a local model or another compatible API endpoint.

• Is Butterfish open source?

  Yes, Butterfish is an open-source project licensed under the MIT license.

• What are the other utilities provided by Butterfish besides the shell wrapper?

  Butterfish also includes utilities for direct LLM prompting, generating shell commands, semantically summarizing files, and managing embeddings of local files.

• How does Butterfish handle long command outputs or history?

  Butterfish manages history within token limits for API requests. Long command outputs are truncated to a configurable token limit, and older history items may fall outside the context window.

• Can I customize the prompts sent to the AI?

  Yes, Butterfish makes prompts transparent and configurable. You can edit the prompt wrappers located in `~/.config/butterfish/prompts.yaml`.

• What is the 'Unsafe Goal Mode'?

  Unsafe Goal Mode, initiated with '!!', allows the AI to execute commands without confirmation. This mode is potentially dangerous and should be used with caution.