About

fish-ai adds AI functionality to Fish shell. It should run on any system with Python and git installed.

Originally based on Tom Dörr's fish.codex repository, but with some additional functionality.

It can be hooked up to OpenAI, Azure OpenAI, Google, Hugging Face, or a self-hosted LLM behind any OpenAI-compatible API.

If you like it, please add a ⭐. If you don't like it, create a PR. 😆

🎥 Demo

👨‍🔧 How to install

Create a configuration

Create a configuration file ~/.config/fish-ai.ini.

If you use a self-hosted LLM:

[fish-ai]
configuration = self-hosted

[self-hosted]
provider = self-hosted
server = https://<your server>:<port>/v1
model = <your model>
api_key = <your API key>

If you are self-hosting, my recommendation is to use Ollama with Llama 3 70B. An out of the box configuration running on localhost could then look something like this:

[fish-ai]
configuration = local-llama

[local-llama]
provider = self-hosted
server = http://localhost:11434/v1
model = llama3

If you use OpenAI:

[fish-ai]
configuration = openai

[openai]
provider = openai
model = gpt-4-turbo
api_key = <your API key>
organization = <your organization>

If you use Azure OpenAI:

[fish-ai]
configuration = azure

[azure]
provider = azure
server = https://<your instance>.openai.azure.com
model = <your deployment name>
api_key = <your API key>

If you use Gemini:

[fish-ai]
configuration = gemini

[gemini]
provider = google
api_key = <your API key>

If you use Hugging Face:

[fish-ai]
configuration = huggingface

[huggingface]
provider = huggingface
email = <your email>
password = <your password>
model = meta-llama/Meta-Llama-3-70B-Instruct

Available models are listed here. Note that 2FA must be disabled on the account.

Install fish-ai

Install the plugin. You can install it using fisher.

fisher install realiserad/fish-ai

For detailed installation instructions tailored for your distribution, see the installation tests.

🙉 How to use

Transform comments into commands and vice versa

Type a comment (anything starting with #), and press Ctrl + P to turn it into shell command!

You can also run it in reverse. Type a command and press Ctrl + P to turn it into a comment explaining what the command does.

Autocomplete commands

Begin typing your command and press Ctrl + Space to display a list of completions in fzf (it is bundled with the plugin, no need to install it separately). Completions load in the background and show up as they become available.

Suggest fixes

If a command fails, you can immediately press Ctrl + Space at the command prompt to let fish-ai suggest a fix!

🤸 Additional options

You can tweak the behaviour of fish-ai by putting additional options in the active section of your fish-ai.ini file.

Explain in a different language

To explain shell commands in a different language, set the language option to the name of the language. For example:

[fish-ai]
configuration = foo

[foo]
language = Swedish

This will only work well if the LLM you are using has been trained on a dataset with the chosen language.

Change the temperature

Temperature is a decimal number between 0 and 1 controlling the randomness of the output. Higher values make the LLM more creative, but may impact accuracy. The default value is 0.2.

Here is an example of how to increase the temperature to 0.5.

[fish-ai]
configuration = foo

[foo]
temperature = 0.5

This option is not supported when using the huggingface provider.

Number of completions

To change the number of completions suggested by the LLM when pressing Ctrl + Space, set the completions option. The default value is 5.

Here is an example of how you can increase the number of completions to 10:

[fish-ai]
configuration = foo

[foo]
completions = 10

Personalise completions using commandline history

You can personalise completions suggested by the LLM by sending an excerpt of your commandline history.

To enable it, specify the maximum number of commands from the history to send to the LLM using the history_size option. The default value is 0 (do not send any commandline history).

[fish-ai]
configuration = foo

[foo]
history_size = 5

🎭 Switch between contexts

You can switch between different sections in the configuration using the fish_ai_switch_context command.

🐾 Data privacy

When using the plugin, fish-ai submits the name of your OS and the commandline buffer to the LLM.

When you codify a command, it also sends the contents of any files you mention (as long as the file is readable), and when you explain or autocomplete a command, the manpage of the current command is provided to the LLM for reference.

fish-ai can also send an exerpt of your command line history when autocompleting a command. This is disabled by default.

Finally, to fix the previous command, the previous commandline buffer, along with any terminal output and the corresponding exit code is sent to the LLM.

If you are concerned with data privacy, you should use a self-hosted LLM. When hosted locally, no data ever leaves your machine.

🔨 Development

This repository ships with a devcontainer.json which can be used with GitHub Codespaces or Visual Studio Code with the Dev Containers extension.

To install fish-ai from a local copy, use fisher:

fisher install .

Enable debug logging

Enable debug logging by putting debug = True in your fish-ai.ini. Logging is done to syslog by default (if available). You can also enable logging to file using log = <path to file>, for example:

[fish-ai]
configuration = foo

[foo]
debug = True
log = ~/.fish-ai/log.txt

Run the tests

The installation tests are packaged into containers and can be executed locally with e.g. docker.

docker build -f tests/ubuntu-22/Dockerfile .
docker build -f tests/fedora-40/Dockerfile .
docker build -f tests/archlinux-base/Dockerfile .

The Python modules containing most of the business logic can be tested using pytest.