{"id":28484294,"url":"https://github.com/bernoussama/lazyshell","last_synced_at":"2025-06-29T17:32:49.652Z","repository":{"id":294695843,"uuid":"987793163","full_name":"bernoussama/lazyshell","owner":"bernoussama","description":"AI CLI tool that generates and executes shell commands using AI","archived":false,"fork":false,"pushed_at":"2025-06-24T02:01:48.000Z","size":578,"stargazers_count":23,"open_issues_count":15,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-26T14:57:51.932Z","etag":null,"topics":["ai","linux","llm","posix","shell","terminal"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bernoussama.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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-21T15:37:55.000Z","updated_at":"2025-06-20T19:05:48.000Z","dependencies_parsed_at":"2025-05-21T16:48:18.371Z","dependency_job_id":"9a039317-8477-4453-96f4-0be6999e1ebf","html_url":"https://github.com/bernoussama/lazyshell","commit_stats":null,"previous_names":["bernoussama/clai"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/bernoussama/lazyshell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bernoussama%2Flazyshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bernoussama%2Flazyshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bernoussama%2Flazyshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bernoussama%2Flazyshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bernoussama","download_url":"https://codeload.github.com/bernoussama/lazyshell/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bernoussama%2Flazyshell/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262637495,"owners_count":23341154,"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","linux","llm","posix","shell","terminal"],"created_at":"2025-06-07T22:06:41.951Z","updated_at":"2025-06-29T17:32:49.639Z","avatar_url":"https://github.com/bernoussama.png","language":"TypeScript","funding_links":[],"categories":["\u003ca name=\"ai-cli-commands\"\u003e\u003c/a\u003eAI terminal command generator"],"sub_categories":[],"readme":"\n\u003cdiv align=\"center\"\u003e\n\n# LazyShell\n\n\u003cimg width=\"200\" align=\"center\" alt=\"lsh-logo\" src=\"https://github.com/user-attachments/assets/f94fbe8d-0be9-474c-9321-4caa27091c0f\" /\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![npm version](https://badge.fury.io/js/lazyshell.svg)](https://badge.fury.io/js/lazyshell)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/bernoussama/lazyshell/workflows/CI/badge.svg)](https://github.com/bernoussama/lazyshell/actions)\n[![Evals](https://github.com/bernoussama/lazyshell/workflows/Evals/badge.svg)](https://github.com/bernoussama/lazyshell/actions)\n[![AI Powered](https://img.shields.io/badge/AI-Powered-blue?logo=huggingface\u0026logoColor=white)](https://github.com/bernoussama/lazyshell)\n![NPM Downloads](https://img.shields.io/npm/d18m/lazyshell)\n\n\u003c/div\u003e\n\n\u003ch4 align=\"center\"\u003e\n\nA smart CLI tool that generates and executes shell commands using AI\n\n\u003c/h4\u003e\n\n\u003cp align=\"center\"\u003e\n   \u003cimg alt=\"Gif Demo\" width=\"100%\" src=\"https://github.com/user-attachments/assets/1699d100-d73a-43d9-8b69-5ba8e50fcdc7\" \u003e\n\u003c/p\u003e\n\nLazyShell is a command-line interface that helps you quickly generate and execute shell commands using AI. It supports multiple AI providers and provides an interactive configuration system for easy setup.\n\n## Features ✨\n\n- 🔍 Generates shell commands from natural language descriptions\n- ⚡ Supports multiple AI providers (Groq, Google Gemini, OpenRouter, Anthropic, OpenAI, Ollama, Mistral)\n- 🔧 Interactive configuration system - no manual environment setup needed\n- 🔒 Safe execution with confirmation prompt\n- 🚀 Fast and lightweight\n- 🔄 Automatic fallback to environment variables\n- 💾 Persistent configuration storage\n- 📋 **Automatic clipboard integration** - generated commands are copied to clipboard\n- 🧪 **Built-in evaluation system for testing AI performance**\n- 🏆 **Model benchmarking capabilities**\n- 🤖 **LLM Judge evaluation system**\n- ⚙️ **CI/CD integration with automated quality checks**\n- 🖥️ **System-aware command generation** - detects OS, distro, and package manager\n- 🔄 **Command refinement** - iteratively improve commands with AI feedback\n\n## Installation 📦\n\n### Using npm\n\n```bash\nnpm install -g lazyshell\n```\n\n### Using yarn\n\n```bash\nyarn global add lazyshell\n```\n\n### Using pnpm\n\n```bash\npnpm add -g lazyshell\n```\n\n### Using bun (recommended)\n\n```bash\nbun add -g lazyshell\n```\n\n### Using Install Script (experimental)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/bernoussama/lazyshell/main/install | bash\n```\n\n## Quick Start 🚀\n\n1. **First Run**: LazyShell will automatically prompt you to select an AI provider and enter your API key:\n\n   ```bash\n   lazyshell \"find all files larger than 100MB\"\n   # or use the short alias\n   lsh \"find all files larger than 100MB\"\n   ```\n\n2. **Interactive Setup**: Choose from supported providers:\n   - **Groq** - Fast LLaMA models with great performance\n   - **Google Gemini** - Google's latest AI models  \n   - **OpenRouter** - Access to multiple models including free options\n   - **Anthropic Claude** - Powerful reasoning capabilities\n   - **OpenAI** - GPT models including GPT-4\n   - **Ollama** - Local models (no API key required)\n   - **Mistral** - Mistral AI models for code generation\n   - **LMStudio** - Local models via LMStudio (experimental, no API key required)\n\n3. **Automatic Configuration**: Your preferences are saved to `~/.lazyshell/config.json` and used for future runs.\n\n4. **Clipboard Integration**: Generated commands are automatically copied to your clipboard for easy pasting.\n\n## Configuration 🔧\n\n### Interactive Setup (Recommended)\n\nOn first run, LazyShell will guide you through:\n\n1. Selecting your preferred AI provider\n2. Entering your API key (if required)\n3. Automatically saving the configuration\n\n### Configuration Management\n\n```bash\n# Open configuration UI\nlazyshell config\n```\n\n### Manual Environment Variables (Optional)\n\nYou can still use environment variables as before:\n\n```bash\nexport GROQ_API_KEY='your-api-key-here'\n# OR\nexport GOOGLE_GENERATIVE_AI_API_KEY='your-api-key-here'\n# OR\nexport OPENROUTER_API_KEY='your-api-key-here'\n# OR\nexport ANTHROPIC_API_KEY='your-api-key-here'  \n# OR\nexport OPENAI_API_KEY='your-api-key-here'\n```\n\n\u003e **Note**: Ollama and LMStudio don't require API keys as they run models locally.\n\n### Configuration File Location\n\n- **Linux/macOS**: `~/.lazyshell/config.json`\n- **Windows**: `%USERPROFILE%\\.lazyshell\\config.json`\n\n## Supported AI Providers 🤖\n\n| Provider | Models | API Key Required | Notes |\n|----------|--------|------------------|-------|\n| **Groq** | LLaMA 3.3 70B | Yes | Fast inference, excellent performance |\n| **Google Gemini** | Gemini 2.0 Flash Lite | Yes | Latest Google AI models |\n| **OpenRouter** | Multiple models | Yes | Includes free tier options |\n| **Anthropic** | Claude 3.5 Haiku | Yes | Advanced reasoning capabilities |\n| **OpenAI** | GPT-4o Mini | Yes | Industry standard models |\n| **Ollama** | Local models | No | Run models locally |\n| **Mistral** | Devstral Small | No | Code-optimized models |\n| **LMStudio** | Local models | No | **Experimental** - Local models via LMStudio |\n\n## Usage Examples 🚀\n\n### Basic Usage\n\n```bash\nlazyshell \"your natural language command description\"\n# or use the short alias\nlsh \"your natural language command description\"\n```\n\n### Silent Mode\n\n```bash\nlazyshell -s \"find all JavaScript files\"  # No explanation, just the command\nlsh --silent \"show disk usage\"            # Same with long flag\n```\n\n### Examples\n\n```bash\n# Find files\nlazyshell \"find all JavaScript files modified in the last 7 days\"\n\n# System monitoring  \nlazyshell \"show disk usage sorted by size\"\n\n# Process management\nlazyshell \"find all running node processes\"\n\n# Docker operations\nlazyshell \"list all docker containers with their memory usage\"\n\n# File operations\nlazyshell \"compress all .log files in this directory\"\n\n# Package management (system-aware)\nlazyshell \"install docker\"  # Uses apt/yum/pacman/etc based on your distro\n```\n\n### Interactive Features\n\n- **Execute**: Run the generated command immediately\n- **Refine**: Modify your prompt to get a better command\n- **Cancel**: Exit without running anything\n- **Clipboard**: Commands are automatically copied for manual execution\n\n## System Intelligence 🧠\n\nLazyShell automatically detects your system environment:\n\n- **Operating System**: Linux, macOS, Windows\n- **Linux Distribution**: Ubuntu, Fedora, Arch, etc.\n- **Package Manager**: apt, yum, dnf, pacman, zypper, etc.\n- **Shell**: bash, zsh, fish, etc.\n- **Current Directory**: Provides context for relative paths\n\nThis enables LazyShell to generate system-appropriate commands and suggest the right package manager for installations.\n\n## Evaluation System 🧪\n\nLazyShell includes a flexible evaluation system for testing and benchmarking AI performance:\n\n```typescript\nimport { runEval, Levenshtein, LLMJudge, createLLMJudge } from './lib/eval';\n\nawait runEval(\"My Eval\", {\n  // Test data function\n  data: async () =\u003e {\n    return [{ input: \"Hello\", expected: \"Hello World!\" }];\n  },\n  // Task to perform  \n  task: async (input) =\u003e {\n    return input + \" World!\";\n  },\n  // Scoring methods\n  scorers: [Levenshtein, LLMJudge],\n});\n```\n\n### Built-in Scorers\n\n- **ExactMatch**: Perfect string matching\n- **Levenshtein**: Edit distance similarity  \n- **Contains**: Substring matching\n- **LLMJudge**: AI-powered quality evaluation\n- **createLLMJudge**: Custom AI judges with specific criteria\n\n### LLM Judge Features\n\n- **AI-Powered Evaluation**: Uses LLMs to evaluate command quality without expected outputs\n- **Multiple Criteria**: Quality, correctness, security, efficiency assessments\n- **Rate Limiting**: Built-in retry logic and exponential backoff\n- **Configurable Models**: Use different AI models for judging\n\n### Features\n\n- Generic TypeScript interfaces for any evaluation task\n- Multiple scoring methods per evaluation\n- Async support for LLM-based tasks\n- Detailed scoring reports with averages\n- Error handling for failed test cases\n\nSee [docs/EVALUATION.md](docs/EVALUATION.md) for complete documentation.\n\n## Model Benchmarking 🏆\n\nLazyShell includes comprehensive benchmarking capabilities to compare AI model performance:\n\n### Running Benchmarks\n\n```bash\n# Build and run benchmarks\npnpm build\nnode dist/bench_models.mjs\n```\n\n### Benchmark Features\n\n- **Multi-Model Testing**: Compare Groq, Gemini, Ollama, Mistral, and OpenRouter models\n- **Performance Metrics**: Response time, success rate, and output quality\n- **Standardized Prompts**: Consistent test cases across all models\n- **JSON Reports**: Detailed results saved to `benchmark-results/` directory\n\n### Available Models\n\n- `llama-3.3-70b-versatile` (Groq)\n- `gemini-2.0-flash-lite` (Google)\n- `devstral-small-2505` (Mistral)\n- `ollama3.2` (Ollama)\n- `or-devstral` (OpenRouter)\n\n## CI Evaluations 🚦\n\nLazyShell includes automated quality assessments that run in CI to ensure consistent performance:\n\n### Overview\n\n- **Automated Testing**: Runs on every PR and push to main/develop\n- **Threshold-Based**: Configurable quality thresholds that must be met\n- **LLM Judges**: Uses AI to evaluate command quality, correctness, security, and efficiency\n- **GitHub Actions**: Integrated with CI/CD pipeline\n\n### Quick Setup\n\n1. Add `GROQ_API_KEY` to your GitHub repository secrets\n2. Evaluations run automatically with 70% threshold by default\n3. CI fails if quality scores drop below the threshold\n\n### Local Testing\n\n```bash\n# Run CI evaluations locally\npnpm eval:ci\n```\n\n### Custom Evaluation Scripts\n\n```bash\n# Run basic evaluations\npnpm build \u0026\u0026 node dist/lib/basic.eval.mjs\n\n# Run LLM judge evaluation\npnpm build \u0026\u0026 node dist/lib/llm-judge.eval.mjs\n\n# Test AI library\npnpm build \u0026\u0026 node dist/test-ai-lib.mjs\n\n# Run example evaluations\npnpm build \u0026\u0026 node dist/lib/example.eval.mjs\n```\n\nSee [docs/CI_EVALUATIONS.md](docs/CI_EVALUATIONS.md) for complete setup and configuration guide.\n\n## Development 🛠️\n\n### Prerequisites\n\n- Node.js 18+\n- pnpm (recommended)\n\n### Setup\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/bernoussama/lazyshell.git\n   cd lazyshell\n   ```\n\n2. Install dependencies:\n\n   ```bash\n   pnpm install\n   ```\n\n3. Build the project:\n\n   ```bash\n   pnpm build\n   ```\n\n4. Link the package for local development:\n\n   ```bash\n   pnpm link --global\n   ```\n\n### Available Scripts\n\n```bash\npnpm x                    # Quick run with jiti (development)\npnpm build               # Compile TypeScript with pkgroll\npnpm typecheck           # Type checking only\npnpm lint                # Check code formatting and linting\npnpm lint:fix            # Fix formatting and linting issues\npnpm eval:ci             # Run CI evaluations locally\npnpm release:patch       # Build, version bump, publish, and push\npnpm prerelease          # Build, prerelease version, publish, and push\n```\n\n### Project Structure\n\n```\nsrc/\n├── index.ts              # Main CLI entry point\n├── utils.ts              # Utility functions (command execution, history)\n├── bench_models.ts       # Model benchmarking script\n├── test-ai-lib.ts        # AI library testing script\n├── commands/\n│   └── config.ts         # Configuration UI command\n├── helpers/\n│   ├── index.ts          # Helper exports\n│   └── package-manager.ts # System package manager detection\n└── lib/\n    ├── ai.ts             # AI provider integrations and command generation\n    ├── config.ts         # Configuration management\n    ├── eval.ts           # Evaluation framework\n    ├── basic.eval.ts     # Basic evaluation examples\n    ├── ci-eval.ts        # CI evaluation script\n    ├── example.eval.ts   # Example evaluation scenarios\n    └── llm-judge.eval.ts # LLM judge evaluation examples\n```\n\n### Development Features\n\n- **TypeScript**: Full type safety and modern JavaScript features\n- **pkgroll**: Modern bundling with tree-shaking\n- **jiti**: Fast development with TypeScript execution\n- **Watch Mode**: Auto-compilation during development\n- **Modular Architecture**: Clean separation of concerns\n- **ESM**: Modern ES modules throughout\n\n## Troubleshooting 🔧\n\n### Configuration Issues\n\n- **Invalid configuration**: Delete `~/.lazyshell/config.json` to reset or use `lazyshell config`\n- **API key errors**: Run `lazyshell config` to re-enter your API key\n- **Provider not working**: Try switching to a different provider in the configuration\n\n### Environment Variables\n\nLazyShell will automatically fall back to environment variables if the config file is invalid or incomplete.\n\n### Common Issues\n\n- **Clipboard not working**: Ensure your system supports clipboard operations\n- **Model timeout**: Some models (especially Ollama) may take longer to respond\n- **Rate limiting**: Built-in retry logic handles temporary rate limits\n- **Command not found**: Make sure the package is properly installed globally\n\n### Debug Mode\n\nFor troubleshooting, you can check:\n\n- Configuration file: `~/.lazyshell/config.json`\n- System detection: The AI considers your OS, distro, and package manager\n- Command history: Generated commands are added to your shell history\n\n## Contributing 🤝\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n### Development Guidelines\n\n- Follow TypeScript best practices\n- Add tests for new features\n- Update documentation as needed\n- Run evaluations before submitting PRs\n- Use the KISS principle (Keep It Simple Stupid)\n- Follow GitHub flow (create feature branches)\n\n## License 📄\n\nThis project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [Commander.js](https://github.com/tj/commander.js/)\n- Interactive prompts powered by [@clack/prompts](https://github.com/natemoo-re/clack)\n- Clipboard integration via [@napi-rs/clipboard](https://github.com/napi-rs/node-rs)\n- AI SDK integration with [Vercel AI SDK](https://github.com/vercel/ai)\n- Bundled with [pkgroll](https://github.com/privatenumber/pkgroll)\n- Powered by AI models from multiple providers\n- Inspired by the need to be lazy (in a good way!)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbernoussama%2Flazyshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbernoussama%2Flazyshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbernoussama%2Flazyshell/lists"}