What The Shell 🐚

An intelligent AI-powered shell command agent that converts natural language to secure shell commands using LangGraph orchestration.

🚀 Features

• Natural Language Processing: Convert everyday language to precise shell commands
• Multi-Layer Security: Comprehensive validation and safety checks
• Cross-Platform Support: Windows (PowerShell), Linux (Bash), and macOS
• Real-time Execution: Interactive command confirmation and execution
• OS-Aware Commands: Generates platform-specific commands automatically
• Rich Terminal UI: Beautiful, syntax-highlighted interface
• LangGraph Workflow: Sophisticated AI orchestration pipeline

Usage Example

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   User Input    │───▶│   OS Detection  │───▶│  LangGraph      │
│  Natural Lang   │    │   & Context     │    │  Workflow       │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                        │
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Command       │◀───│   AI Command    │◀───│   Groq API      │
│   Execution     │    │   Generator     │    │   LLM           │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                        │                     │
         ▼                        ▼                     ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Result        │    │   Safety        │    │   User          │
│   Display       │    │   Checker       │    │   Confirmation  │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🛠️ Tech Stack

Component	Technology
AI Framework	LangChain + LangGraph
LLM Provider	Groq API
Language	Python 3.10+
CLI Interface	Rich Terminal Library
Command Execution	PowerShell, Bash
Validation	Custom Security Layer

📋 Prerequisites

• Python 3.10 or higher
• Groq API key (free at console.groq.com)
• Windows PowerShell, Linux Bash, or macOS Terminal

⚡ Quick Start

1. Clone Repository

git clone https://github.com/srrishtea/what-the-shell.git
cd what-the-shell

2. Install Dependencies

pip install -r requirements.txt

3. Configure API Key

Edit config/settings.py and add your Groq API key:

GROQ_API_KEY = "your_groq_api_key_here"

4. Run Application

python main.py

🎯 Usage Examples

Basic Commands

User: "list all python files in current directory"
AI: Get-ChildItem -Filter "*.py" -Recurse

User: "show disk usage of folders here"  
AI: Get-ChildItem | Measure-Object -Property Length -Sum

User: "find files modified today"
AI: Get-ChildItem -Recurse | Where-Object {$_.LastWriteTime -ge (Get-Date).Date}

Interactive Features

• Type help for available commands
• Type status to view system information
• Type os to change operating system preference
• Type quit or exit to close application

🔧 Configuration

Operating System Selection

On first run, the application will ask you to select your preferred OS:

1. Windows (PowerShell/CMD)
2. Linux (Bash/Shell)
3. macOS (Bash/Shell)
4. Auto-detect

Security Settings

The application includes multiple security layers:

• Command validation and sanitization
• User confirmation for all commands
• OS-specific command generation
• Safe execution environment

📂 Project Structure

what-the-shell/
├── main.py                 # Application entry point
├── config/
│   └── settings.py         # Configuration management
├── agents/
│   ├── command_generator.py   # AI command generation
│   ├── safety_checker.py     # Security validation
│   └── executor.py           # Command execution
├── graph/
│   └── shell_graph.py        # LangGraph workflow
├── utils/
│   ├── prompts.py            # AI prompts
│   └── validators.py         # Input validation
├── images/                 # Documentation assets
├── requirements.txt        # Python dependencies
└── README.md              # Project documentation

🔒 Security Features

• Input Validation: Sanitizes user input and commands
• Command Whitelisting: Only allows safe, pre-approved commands
• Pattern Blacklisting: Blocks dangerous command patterns
• User Confirmation: Requires explicit approval before execution
• Resource Monitoring: Tracks CPU and memory usage
• Execution Limits: Enforces timeouts and resource constraints

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📊 Roadmap

• Plugin System: Extensible command modules
• Command History: Persistent command storage
• Multi-Language Support: Support for additional languages
• Web Interface: Browser-based UI option
• Docker Integration: Containerized deployment
• Team Collaboration: Shared command libraries

🐛 Troubleshooting

Common Issues

Issue: ImportError: cannot import name 'ChatGroq' Solution: Install langchain-groq: pip install langchain-groq

Issue: Commands fail with PowerShell errors Solution: Ensure you're running with appropriate permissions

Issue: API rate limiting Solution: Check your Groq API usage and upgrade plan if needed

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• LangChain for the AI framework
• Groq for ultra-fast LLM inference
• Rich for beautiful terminal interfaces
• The open-source community for inspiration and support

📞 Support

• Documentation: Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: Contact Us

---

Made with ❤️ by @srrishtea

⭐ Star this repository if you find it helpful!