{"id":13586953,"url":"https://github.com/jonboh/shai","last_synced_at":"2025-04-13T11:08:46.059Z","repository":{"id":189799344,"uuid":"666784489","full_name":"jonboh/shai","owner":"jonboh","description":"A Shell AI assistant. It can help you write and explain commands, without having to leave your comfy terminal!","archived":false,"fork":false,"pushed_at":"2024-01-14T10:06:15.000Z","size":46160,"stargazers_count":20,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-13T11:08:39.791Z","etag":null,"topics":["ai","chatgpt","openassistant","rust","shell","terminal"],"latest_commit_sha":null,"homepage":"https://jonboh.dev/posts/shai/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonboh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-07-15T15:08:06.000Z","updated_at":"2025-02-26T15:37:34.000Z","dependencies_parsed_at":"2023-08-21T20:42:08.791Z","dependency_job_id":"cfbc66d2-399f-44ef-b653-d96d19ea5a08","html_url":"https://github.com/jonboh/shai","commit_stats":null,"previous_names":["jonboh/shai"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonboh%2Fshai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonboh%2Fshai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonboh%2Fshai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonboh%2Fshai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonboh","download_url":"https://codeload.github.com/jonboh/shai/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248703198,"owners_count":21148118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","chatgpt","openassistant","rust","shell","terminal"],"created_at":"2024-08-01T15:05:55.780Z","updated_at":"2025-04-13T11:08:46.032Z","avatar_url":"https://github.com/jonboh.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# Shai. Shell AI Assitant\nShai is a Shell AI assistant. Its purpose is to help you interact with your machine through\na command line interface. It has two main ways to achieve this.\n- Command Generation: Shai allows you to quickly ask a LLM model to generate a command based on what it should do.\n- Command Explanation: Given a command Shai will explain what a command will do and its side effects.\n\nYou'll probably interact with Shai primarily in its command generation mode.\n![main example](./assets/git.gif)\n\nYou can also ask Shai to explain the command it just generated:\n![explain generated command](./assets/explanation.gif)\n\nor a command that is currently in your buffer line:\n![explain buffer line command](./assets/explanation_buffer.gif)\n\nNote that the explanation will not take into account your initial prompt. This is purposely done to avoid biasing\nthe model explanation. In addition this can help double check that the model generated the correct command and detect\nmodel hallucinations.\n\nThe model explanations will briefly explain the command and enumerate a list of common side-effects.\nIn addition, if the command is potentially dangerous the model will usually point it out.\n\nAs a backend you can use any of the following OpenAI models:\n- GPT-3.5-turbo\n- GPT-3.5-turbo-16k\n- GPT-4\n- GPT-4-32k\n\nThis might be anecdotal, but I've sometimes experienced lower latencies with the larger context models.\n\nFor the time being I don't have access to the gpt-4 models API, but they should work if your account\ndoes have access. All examples have been generated with GPT-3.5-turbo, so I expect the results from\nGPT-4 to be equivalent or better (specially when the request has several moving parts, like pipelines\nor redirection).\n\nSupport for other models is planned. See [Current Status](#current-status)\n\nNote that Shai is not intended to replace a solid knowledge of your system or its commands, but it\ncan help ease the burden of memorizing every single flag and command syntax. The OpenAI GPT models are\nby no means foolproof, and the best results are usually achieved when you as an operator already know\nthe terminology and capabilities related to the command you want to generate. It can also be a resource\nto explain commands taken from tutorials or forums.\n\n\n## Installation\n##### Cargo\n```bash\ncargo install shai\n```\nRemember to add `.cargo/bin` to your `PATH`.\n\nThis method should be available for all platforms, but you'll need to have Cargo installed, use \n[rustup](https://rustup.rs/) to install it.\n\nNote: See the [next section](#shell-integration) to integrate shai and allow it \nto interact with your buffer line.\n\n##### Arch Linux. AUR:\n```bash\nyay -S shai\n```\n\n##### Other\nUse the [latest release](https://github.com/jonboh/shai/releases/latest) in this github repo.\nPut the binary in a location that is included in your `PATH`, source the corresponding integration\nshell script (see [next section](#shell-integration)) in your rc file and you should be good to go.\n\n### Shell Integration\nI've developed Shai with the aim to have it very closely integrated in the shell. I tend to use it similarly to\n[fzf](https://github.com/junegunn/fzf), so one key-shortcut away.\n\nIn this repository you will find the scripts needed to integrate Shai in your shell experience.\nThe following list contains the shells that are currently supported and the planned ones.\n\n- [x] Bash\n- [x] Zsh\n- [x] Fish\n- [x] Nushell\n- [x] PowerShell\n- [ ] Window CMD\n\nIn order for Shai to be available through shortcuts you'll need to source the corresponding\nscript. These scripts provide a default binding, modify it to adapt it to your needs.\nAll these scripts perform the same function, the setup a function that is called through the keybind.\nThe function takes the current content of your shell buffer, forwards it to Shai, and if the\ncommand generation interface is being used and Shai is exited with `Ctrl+a` (accept), the buffer\nline is modified with the command generated. In most cases the function essentially highjacks the\ncommand edition capabilities of the shell treating Shai as a text editor.\n\n| Shell           | Integration file           |\n| --------------- | ---------------            |\n| Bash            | `bash_assistant.sh`        |\n| Zsh             | `zsh_assistant.zsh`        |\n| Fish            | `fish_assistant.fish`      |\n| Nushell         | `nushell_assistant.nu`     |\n| PowerShell      | `powershell_assistant.ps1` |\n\nIf you just install the binary you can generate the integration script using shai\n```bash\nshai generate-script --shell \u003cyour-shell, one of {bash, zsh, fish, nushell, powershell}\u003e\n# e.g\nshai generate-script --shell zsh \u003e zsh_assistant.zsh\n# then in your .zshrc\nsource zsh_assistant.zsh\n```\nRemember to source the resulting script in you rc, otherwise you won't have the shortcuts available.\n\nDepending on what model you use you might need to provide the API key as an environment variable. For the OpenAI models\nyou could set it with:\n```bash\nexport OPENAI_API_KEY=$(\u003ccommand_to_get_API_key\u003e)\n# if you have it on a text file\nexport OPENAI_API_KEY=$(cat ~/.secrets/chatgpt.key)\n```\nSee [here](https://help.openai.com/en/articles/4936850-where-do-i-find-my-secret-api-key) how to get your OpenAI API key.\n\n## How to use it\n### Shell Shortcuts\nIf you don't modify the shell integration script the shortcuts will be the following:\n- `Alt+s` : Command Generation\n- `Alt+e` : Command Explanation\n\nYou can change these shortcuts on the shell integration files. They have been chosen to avoid collision with already existing\nshortcuts in *readline*.\n\n### Shai Controls\n- `Enter` : Send Prompt\n- `Ctrl+c` : Exit Shai\n- `Esc` : Cancel current request\n\n#### Command Generation\nWhen a command is generated the following controls are also available:\n- `Ctrl+a` : Accept generated command\n    - This will check that the model followed the format instructions, when the model provides a long answer\n        this shortcut will retrieve only the text inside markdown code blocks.\n- `Ctrl+r` : Accept generated command (raw)\n    - This will accept the input from the model without any check\n- `Ctrl+e` : Explain generated command\n    - This will generate an explanation for the command that Shai has just generated.\n\nThese keybinds cannot currently be changed.\n\n\n## Examples\n### Git\n![Get the commit hash in which a string was introduced](./assets/git_log_insert_string.png)\n![Get the commit hash of the commits that include string](./assets/git_message_grep.png)\n![Get the commit hash of the commits that modify a file](./assets/git_hashes_file.png)\n\n\n### Miscellaneous\nRun bash on a running container:\n![run bash on a running container](./assets/docker_exec.gif)\n\nMake a ssh tunnel:\n![SSH Tunnel](./assets/ssh_tunnel.png)\n\nSimple ffmpeg operations, or command modifications:\n![Make a GIF from a video file](./assets/ffmpeg_gif.png)\n![Modify a ffmpeg command](./assets/modify_ffmpeg.png)\n\nDiscard command output:\n![Discard output of a terminal](./assets/discard_output.gif)\n\n## Current Status\nAt the moment Shai is memoryless, when you send a prompt it is sent to the model without any\ncontext from your previous prompts. The purpose of Shai is not to be a conversational application but\nto quickly generate commands leveraging LLMs. I might implement conversational functionality later in\nthe future if it improves the commands produced.\n\nI plan to add support for other models like [OpenAssistant](https://github.com/LAION-AI/Open-Assistant)\nonce they provide an API or a way to run it locally is available (even if the requirements for the machine\nare steep, but within a high-end desktop). If you have pointers for other similar models that can be run\nlocally or have an available API please, fill an issue and I will try to add support for it.\n\n\n### Context Awareness. \nYou can modify the assumed Operating System or distro to get more relevant results. This information\nis provided in the `--operating-system` option. You can modify your integration script with the appropriate\nvalue.\n\nIn the same way the `--shell` option lets the model know in which shell it is running, this can help the model\nuse shell specific features. However, for modern shells like `nushell` this can actually confuse the model as it won't\nhave a lot of information about this shell in its training data. In cases like this it might be better to\nlet the model believe it is running on another shell (like `bash`).\n\n#### Experimental Options\nInitially I envisioned Shai as a more capable assistant to which context about the current state\nof your machine could be forwarded, and it would act accordingly. There are some options that are\ndisabled by default:\n\n| Option           | Description                                                                                                  |\n| ---------------- | ---------------                                                                                              |\n| `pwd`            | Provides the model with the current working directory                                                        |\n| `depth`          | depth with which to run the `tree` command. It provides context about ther current directory and its content |\n| `environment`    | The list of environment variables set (only their name is passed to the model)                               |\n| `programs`       | The list of available programs to the model with which to complete the task                                  |\n\n\nI have found that the performance of the GPT3.5 model is lacking in this respect. I have\nsome hope that the GPT-4 (or future) models perform better, so the option to forward this context\nto the model is still available, if you find good results with it let me know!\n\n\n## Roadmap\nIn no particular order:\n- [ ] Custom keybindings\n- [ ] Prompt Overrides\n- [ ] Add prompt history navigation.\n- [ ] Add support for other models. (I'd like to make it easy to interact with a locally run model).\n    - [x] OpenAI\n    - [ ] Local\n    - [ ] OpenAssistant (once a public API is available)\n    - [ ] Google Bard (once a public API is available)\n- [ ] Add other shells\n    - [x] Bash\n    - [x] Zsh\n    - [x] Fish\n    - [x] Nushell\n    - [x] PowerShell\n    - [ ] Window CMD\n\n## Acknowlegments\n- [fzf](https://github.com/junegunn/fzf)\n    - fzf is the main inspiration in terms of the integration with the shell\n- [ChatGPT-rs](https://github.com/Maxuss/chatgpt_rs)\n    - I did take some hints from this project to implement the streaming responses from OpenAI.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonboh%2Fshai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonboh%2Fshai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonboh%2Fshai/lists"}