{"id":18883676,"url":"https://github.com/vitali87/llm-shell","last_synced_at":"2026-02-09T12:31:55.339Z","repository":{"id":260378836,"uuid":"881050705","full_name":"vitali87/llm-shell","owner":"vitali87","description":"100% private: enhance your zsh terminal with natural language queries for shell commands using Ollama LLM","archived":false,"fork":false,"pushed_at":"2024-12-06T01:23:23.000Z","size":1501,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-25T21:21:46.381Z","etag":null,"topics":["command-line-tool","developer-tools","linux","llm","macos","ollama","zsh"],"latest_commit_sha":null,"homepage":"https://ollama.com/vitali87/shell-commands","language":"Python","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/vitali87.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"publiccode":null,"codemeta":null}},"created_at":"2024-10-30T20:37:19.000Z","updated_at":"2025-02-15T13:49:21.000Z","dependencies_parsed_at":"2024-10-31T01:29:46.010Z","dependency_job_id":"b597a78c-7b77-4b3c-acdb-7244fffc7f5a","html_url":"https://github.com/vitali87/llm-shell","commit_stats":null,"previous_names":["vitali87/llm-shell"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitali87%2Fllm-shell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitali87%2Fllm-shell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitali87%2Fllm-shell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitali87%2Fllm-shell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vitali87","download_url":"https://codeload.github.com/vitali87/llm-shell/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248505716,"owners_count":21115352,"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":["command-line-tool","developer-tools","linux","llm","macos","ollama","zsh"],"created_at":"2024-11-08T07:08:22.156Z","updated_at":"2026-02-09T12:31:53.206Z","avatar_url":"https://github.com/vitali87.png","language":"Python","funding_links":["https://buymeacoffee.com/vitali87","https://img.buymeacoffee.com/button-api/?text=Buy"],"categories":[],"sub_categories":[],"readme":"# Zsh Ollama Command Helper\n\n\u003cdiv align=\"center\"\u003e\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub stars](https://img.shields.io/github/stars/vitali87/llm-shell)](https://github.com/vitali87/llm-shell/stargazers)\n[![GitHub issues](https://img.shields.io/github/issues/vitali87/llm-shell)](https://github.com/vitali87/llm-shell/issues)\n[![GitHub forks](https://img.shields.io/github/forks/vitali87/llm-shell)](https://github.com/vitali87/llm-shell/network)\n[![Contributors](https://img.shields.io/github/contributors/vitali87/llm-shell)](https://github.com/vitali87/llm-shell/graphs/contributors)\n[![Last Commit](https://img.shields.io/github/last-commit/vitali87/llm-shell)](https://github.com/vitali87/llm-shell/commits/main)\n[![Python](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n\u003ca href=\"https://github.com/vitali87/llm-shell/stargazers\"\u003e\u003cimg src=\"https://reporoster.com/stars/vitali87/llm-shell\" alt=\"Stargazers\"\u003e\u003c/a\u003e\n\n\u003c/div\u003e\n\nThis project enhances your Zsh terminal by allowing you to input natural language queries for shell commands you can't remember. By pressing `Ctrl+B`, your query is sent to an Ollama model, which generates the appropriate command. The command is displayed, and you're prompted to execute it or not (`y/n`).\n\n## 🎮 Demo\n\n\n\nhttps://github.com/user-attachments/assets/64c6c2df-d8a4-4360-adcb-b381a0907f18\n\n\n\n\u003e 💡 Simply type your question and press `Ctrl+B` to get the command you need!\n\n## Table of Contents\n- [Features](#features)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [Customization](#customization)\n- [Troubleshooting](#troubleshooting)\n- [TODO](#todo)\n- [License](#license)\n\n## ✨ Features\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n### 🗣️ Natural Language Queries\nAsk questions in plain English about shell commands\n  \n### 🤖 Model Integration\nUses your locally running Ollama instance with a finetuned model\n  \n### ⚡ Command Execution\nShows the generated command and prompts you to execute it\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n### 🔄 Model Selection\nEasily switch between different Ollama models\n  \n### 🎨 Customizable\nAdjust colors and default settings to your preference\n  \n### 🔒 Privacy-Focused\n100% local execution - your queries never leave your machine\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## Prerequisites\n- **Operating System**: Unix-like system (Linux, macOS).\n\n\n\n\n- **Shell**: Zsh.\n- **Python**: Version 3.11.\n- **Ollama**: Installed and running locally.\n- **jq**: Command-line JSON processor.\n\n## Installation\n\n### 1. Ensure Prerequisites Are Met\n\n#### Install Zsh\nIf you don't have Zsh installed:\n\n```bash\n# On Ubuntu/Debian\nsudo apt update\nsudo apt install zsh\n\n# On macOS (using Homebrew)\nbrew install zsh\n```\n\n#### Install Python 3.11\n```bash\n# On Ubuntu/Debian\nsudo apt update\nsudo apt install python3.11 python3.11-venv\n\n# On macOS (using Homebrew)\nbrew install python@3.11\n```\n\n#### Install Ollama\nFollow the installation instructions from Ollama's official documentation.\n\n#### Install jq\n```bash\n# On Ubuntu/Debian\nsudo apt update\nsudo apt install jq\n\n# On macOS (using Homebrew)\nbrew install jq\n```\n\n### 2. Run the `install.sh` Script\n\n```bash \n./install.sh \n```\n\n### 3. Reload Your Zsh Configuration \n\n```bash \nsource ~/.zshrc \n```\n\n## Configuration\n\n### Default Ollama Model \n\nThe default model is set to `vitali87/shell-commands`. You can change it by editing the `export ZSH_OLLAMA_MODEL` line in your `~/.zshrc`.\n\n```bash \nexport ZSH_OLLAMA_MODEL=\"your-preferred-model\"\n```\n\n## Usage\n\n### Ask a Question \n\nType your natural language query directly into the terminal prompt.\n\n```bash \nhow to list all files modified in the last 24 hours \n```\n\n### Trigger the Helper \n\nPress `Ctrl+B` to activate the helper.\n\n#### Example Output:\n\n```bash \n🤔 Asking Ollama (using model: vitali87/shell-commands)... \nYour query: how to list all files modified in the last 24 hours \nGenerated command: find . -type f -mtime -1 \nExecute? [y/N] \n```\n\n### Execute the Command \n\nPress `y` and hit Enter to execute the command. Press any other key to abort.\n\n## Customization\n\n### Changing the Model \n\n#### List Available Models \n\n```bash \nset_ollama_model \n```\n\n#### Set a Different Model \n\n```bash \nset_ollama_model your_model_name \n```\n\n##### Example:\n\n```bash \nset_ollama_model llama2:7b \n```\n\n### Customizing Colors \n\nThe colors can be adjusted by modifying the color codes in the Zsh configuration.\n\n#### Color Codes:\n- Black: `\\e[30m`\n- Red: `\\e[31m`\n- Green: `\\e[32m`\n- Yellow: `\\e[33m`\n- Blue: `\\e[34m`\n- Magenta: `\\e[35m`\n- Cyan: `\\e[36m`\n- White: `\\e[37m`\n- Reset: `\\e[0m`\n\n#### Steps:\n\nOpen the Zsh configuration file:\n\n```bash \nnano ~/.zshrc \n```\n\nLocate the `ollama_command_helper` function.\n\nModify the echo statements:\n\n```bash \necho -e \"\\e[33mYour query:\\e[0m $user_query\" \necho -e \"\\e[32mGenerated command:\\e[0m $command\" \n```\n\nReplace the color codes with your preferred ones.\n\nSave and exit the editor.\n\nReload your Zsh configuration:\n\n```bash \nsource ~/.zshrc \n```\n\n## Troubleshooting\n\n### Error: No Command Generated \n\nEnsure your Ollama server is running and the specified model is available.\n\n### Dependencies Not Found \n\nMake sure Python 3.11 and jq are installed on your system.\n\n### Virtual Environment Issues \n\nIf you encounter issues with the virtual environment:\n\nRemove the existing virtual environment:\n\n```bash \nrm -rf ~/.config/zsh/ollama_env \n```\n\nRe-run the installation script:\n\n```bash \n./install.sh \n```\n\nReload your Zsh configuration:\n\n```bash \nsource ~/.zshrc \n```\n\n### Powerlevel10k Warning \n\nIf you see a warning related to Powerlevel10k's instant prompt:\n\nPlace the Ollama Command Helper configuration after Powerlevel10k initialization in your `~/.zshrc`.\n\nAlternatively, disable the instant prompt feature in Powerlevel10k.\n\n## 📋 Roadmap \u0026 TODO\n\n\u003cdiv align=\"center\"\u003e\n\n![Progress](https://img.shields.io/badge/Progress-20%25-brightgreen)\n\n\u003c/div\u003e\n\n### 🚀 Upcoming Features\n\n#### User Experience\n- [ ] 🎨 Add color themes support\n  - [ ] Dark mode\n  - [ ] Light mode\n  - [ ] Terminal-native theme\n- [ ] ⌨️ Customizable keyboard shortcuts\n- [ ] 💾 Command history with search functionality\n- [ ] 🔍 Auto-completion suggestions\n\n#### AI/ML Enhancements\n- [ ] 🧠 Context-aware command suggestions\n- [ ] 📊 Learning from user corrections\n\n\n#### Performance \u0026 Integration\n- [ ] ⚡ Improve response time\n- [ ] 🔌 Plugin system for extensions\n- [ ] 📦 Package for different package managers\n  - [ ] Homebrew\n  - [ ] apt\n  - [ ] pip\n\n### 🔄 In Progress\n\n#### User Feedback System\n- [x] Basic feedback collection\n- [ ] 👍 Command rating system (thumbs up/down)\n- [ ] 📝 Feedback submission UI\n- [ ] 📊 Analytics dashboard for feedback\n\n#### Command History Enhancement\n- [x] Basic history storage\n- [ ] 🔍 Searchable command history\n- [ ] 📈 Usage statistics\n- [ ] 🎯 Success/failure tracking\n\n### 🎯 Future Goals\n\n#### Community Features\n- [ ] 👥 Command sharing platform\n- [ ] 🌟 Popular commands repository\n- [ ] 🤝 Community contributions system\n\n#### Documentation\n- [ ] 📚 API documentation\n- [ ] 🎥 Video tutorials\n- [ ] 👩‍💻 Developer guide\n- [ ] 🌍 Internationalization\n\n### ✅ Completed\n- [x] Basic command generation\n- [x] Model selection interface\n- [x] Installation script\n- [x] Basic error handling\n\n\n## Acknowledgments \n\nOllama for providing the LLM serving platform.\n\nOpenAI for the openai Python package.\n\nFeel free to contribute to this project by submitting issues or pull requests.\n\n## 📊 Project Stats\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github-readme-stats.vercel.app/api/pin/?username=vitali87\u0026repo=llm-shell\u0026theme=dark\" alt=\"Repo Card\"/\u003e\n  \n  \u003cimg src=\"https://github-profile-summary-cards.vercel.app/api/cards/profile-details?username=vitali87\u0026theme=dark\" alt=\"Profile Details\"/\u003e\n\u003c/div\u003e\n\n## 👥 Contributors\n\n\u003ca href=\"https://github.com/vitali87/llm-shell/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=vitali87/llm-shell\" /\u003e\n\u003c/a\u003e\n\n\n## 🛠️ Built With\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white\" alt=\"Python\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Shell_Script-121011?style=for-the-badge\u0026logo=gnu-bash\u0026logoColor=white\" alt=\"Shell\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Zsh-121011?style=for-the-badge\u0026logo=gnu-bash\u0026logoColor=white\" alt=\"Zsh\"/\u003e\n\u003c/p\u003e\n\n## 🌟 Show your support\n\nGive a ⭐️ if this project helped you!\n\n\u003ca href=\"https://buymeacoffee.com/vitali87\"\u003e\n  \u003cimg src=\"https://img.buymeacoffee.com/button-api/?text=Buy me a coffee\u0026emoji=\u0026slug=vitali87\u0026button_colour=FFDD00\u0026font_colour=000000\u0026font_family=Cookie\u0026outline_colour=000000\u0026coffee_colour=ffffff\" /\u003e\n\u003c/a\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://visitor-badge.laobi.icu/badge?page_id=vitali87.llm-shell\" alt=\"visitors\"/\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitali87%2Fllm-shell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvitali87%2Fllm-shell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitali87%2Fllm-shell/lists"}