Skip to content
/ shai Public

A Shell AI assistant. It can help you write and explain commands, without having to leave your comfy terminal!

License

Notifications You must be signed in to change notification settings

jonboh/shai

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

70 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Shai. Shell AI Assitant

Shai is a Shell AI assistant. Its purpose is to help you interact with your machine through a command line interface. It has two main ways to achieve this.

  • Command Generation: Shai allows you to quickly ask a LLM model to generate a command based on what it should do.
  • Command Explanation: Given a command Shai will explain what a command will do and its side effects.

You'll probably interact with Shai primarily in its command generation mode. main example

You can also ask Shai to explain the command it just generated: explain generated command

or a command that is currently in your buffer line: explain buffer line command

Note that the explanation will not take into account your initial prompt. This is purposely done to avoid biasing the model explanation. In addition this can help double check that the model generated the correct command and detect model hallucinations.

The model explanations will briefly explain the command and enumerate a list of common side-effects. In addition, if the command is potentially dangerous the model will usually point it out.

As a backend you can use any of the following OpenAI models:

  • GPT-3.5-turbo
  • GPT-3.5-turbo-16k
  • GPT-4
  • GPT-4-32k

This might be anecdotal, but I've sometimes experienced lower latencies with the larger context models.

For the time being I don't have access to the gpt-4 models API, but they should work if your account does have access. All examples have been generated with GPT-3.5-turbo, so I expect the results from GPT-4 to be equivalent or better (specially when the request has several moving parts, like pipelines or redirection).

Support for other models is planned. See Current Status

Note that Shai is not intended to replace a solid knowledge of your system or its commands, but it can help ease the burden of memorizing every single flag and command syntax. The OpenAI GPT models are by no means foolproof, and the best results are usually achieved when you as an operator already know the terminology and capabilities related to the command you want to generate. It can also be a resource to explain commands taken from tutorials or forums.

Installation

Cargo
cargo install shai

Remember to add .cargo/bin to your PATH.

This method should be available for all platforms, but you'll need to have Cargo installed, use rustup to install it.

Note: See the next section to integrate shai and allow it to interact with your buffer line.

Arch Linux. AUR:
yay -S shai
Other

Use the latest release in this github repo. Put the binary in a location that is included in your PATH, source the corresponding integration shell script (see next section) in your rc file and you should be good to go.

Shell Integration

I've developed Shai with the aim to have it very closely integrated in the shell. I tend to use it similarly to fzf, so one key-shortcut away.

In this repository you will find the scripts needed to integrate Shai in your shell experience. The following list contains the shells that are currently supported and the planned ones.

  • Bash
  • Zsh
  • Fish
  • Nushell
  • PowerShell
  • Window CMD

In order for Shai to be available through shortcuts you'll need to source the corresponding script. These scripts provide a default binding, modify it to adapt it to your needs. All these scripts perform the same function, the setup a function that is called through the keybind. The function takes the current content of your shell buffer, forwards it to Shai, and if the command generation interface is being used and Shai is exited with Ctrl+a (accept), the buffer line is modified with the command generated. In most cases the function essentially highjacks the command edition capabilities of the shell treating Shai as a text editor.

Shell Integration file
Bash bash_assistant.sh
Zsh zsh_assistant.zsh
Fish fish_assistant.fish
Nushell nushell_assistant.nu
PowerShell powershell_assistant.ps1

If you just install the binary you can generate the integration script using shai

shai generate-script --shell <your-shell, one of {bash, zsh, fish, nushell, powershell}>
# e.g
shai generate-script --shell zsh > zsh_assistant.zsh
# then in your .zshrc
source zsh_assistant.zsh

Remember to source the resulting script in you rc, otherwise you won't have the shortcuts available.

Depending on what model you use you might need to provide the API key as an environment variable. For the OpenAI models you could set it with:

export OPENAI_API_KEY=$(<command_to_get_API_key>)
# if you have it on a text file
export OPENAI_API_KEY=$(cat ~/.secrets/chatgpt.key)

See here how to get your OpenAI API key.

How to use it

Shell Shortcuts

If you don't modify the shell integration script the shortcuts will be the following:

  • Alt+s : Command Generation
  • Alt+e : Command Explanation

You can change these shortcuts on the shell integration files. They have been chosen to avoid collision with already existing shortcuts in readline.

Shai Controls

  • Enter : Send Prompt
  • Ctrl+c : Exit Shai
  • Esc : Cancel current request

Command Generation

When a command is generated the following controls are also available:

  • Ctrl+a : Accept generated command
    • This will check that the model followed the format instructions, when the model provides a long answer this shortcut will retrieve only the text inside markdown code blocks.
  • Ctrl+r : Accept generated command (raw)
    • This will accept the input from the model without any check
  • Ctrl+e : Explain generated command
    • This will generate an explanation for the command that Shai has just generated.

These keybinds cannot currently be changed.

Examples

Git

Get the commit hash in which a string was introduced Get the commit hash of the commits that include string Get the commit hash of the commits that modify a file

Miscellaneous

Run bash on a running container: run bash on a running container

Make a ssh tunnel: SSH Tunnel

Simple ffmpeg operations, or command modifications: Make a GIF from a video file Modify a ffmpeg command

Discard command output: Discard output of a terminal

Current Status

At the moment Shai is memoryless, when you send a prompt it is sent to the model without any context from your previous prompts. The purpose of Shai is not to be a conversational application but to quickly generate commands leveraging LLMs. I might implement conversational functionality later in the future if it improves the commands produced.

I plan to add support for other models like OpenAssistant once they provide an API or a way to run it locally is available (even if the requirements for the machine are steep, but within a high-end desktop). If you have pointers for other similar models that can be run locally or have an available API please, fill an issue and I will try to add support for it.

Context Awareness.

You can modify the assumed Operating System or distro to get more relevant results. This information is provided in the --operating-system option. You can modify your integration script with the appropriate value.

In the same way the --shell option lets the model know in which shell it is running, this can help the model use shell specific features. However, for modern shells like nushell this can actually confuse the model as it won't have a lot of information about this shell in its training data. In cases like this it might be better to let the model believe it is running on another shell (like bash).

Experimental Options

Initially I envisioned Shai as a more capable assistant to which context about the current state of your machine could be forwarded, and it would act accordingly. There are some options that are disabled by default:

Option Description
pwd Provides the model with the current working directory
depth depth with which to run the tree command. It provides context about ther current directory and its content
environment The list of environment variables set (only their name is passed to the model)
programs The list of available programs to the model with which to complete the task

I have found that the performance of the GPT3.5 model is lacking in this respect. I have some hope that the GPT-4 (or future) models perform better, so the option to forward this context to the model is still available, if you find good results with it let me know!

Roadmap

In no particular order:

  • Custom keybindings
  • Prompt Overrides
  • Add prompt history navigation.
  • Add support for other models. (I'd like to make it easy to interact with a locally run model).
    • OpenAI
    • Local
    • OpenAssistant (once a public API is available)
    • Google Bard (once a public API is available)
  • Add other shells
    • Bash
    • Zsh
    • Fish
    • Nushell
    • PowerShell
    • Window CMD

Acknowlegments

  • fzf
    • fzf is the main inspiration in terms of the integration with the shell
  • ChatGPT-rs
    • I did take some hints from this project to implement the streaming responses from OpenAI.