AI Shell 🤖

**Your Intelligent Command-Line Copilot** [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://github.com/GizzZmo/Ai_shell/releases) [](https://github.com/GizzZmo/Ai_shell/actions/workflows/ci.yml) [](https://github.com/GizzZmo/Ai_shell/actions/workflows/security.yml) [](https://github.com/GizzZmo/Ai_shell/actions/workflows/documentation.yml) [](https://github.com/GizzZmo/Ai_shell/actions/workflows/performance.yml) [](https://github.com/GizzZmo/Ai_shell/actions/workflows/deployment-assets.yml) [](https://codecov.io/gh/GizzZmo/Ai_shell) [](https://github.com/GizzZmo/Ai_shell/security/code-scanning) [](https://github.com/GizzZmo/Ai_shell/issues) [](https://github.com/GizzZmo/Ai_shell/pulls) [](https://github.com/GizzZmo/Ai_shell/stargazers) *Transform natural language into powerful shell commands with AI* [🚀 Quick Start](#quick-start) • [📖 Documentation](#documentation) • [🤝 Contributing](CONTRIBUTING.md) [🐛 Issues](https://github.com/GizzZmo/Ai_shell/issues) • [📊 Workflow Status](WORKFLOW_STATUS.md)

---

Overview

AI Shell is an intelligent, multi-modal command-line assistant that bridges the gap between natural language and complex shell operations. Powered by Large Language Models (LLMs), it translates your requests into executable commands, provides conversational guidance, and integrates with specialized tools like the Metasploit Framework and Wapiti.

Whether you're a beginner learning the command line or a seasoned expert looking to accelerate your workflow, AI Shell adapts to your needs.

✨ Key Features

• 🔄 Multi-Modal Architecture: Four distinct operating modes for different use cases
• 🧠 Advanced LLM Integration: Support for both cloud (Gemini) and local (Ollama) models
• 🔒 Security-First Design: Built-in command validation and user confirmation
• 📊 Command Audit Logging: Comprehensive security tracking and compliance reporting
• 🛡️ Enhanced Threat Detection: 25+ dangerous command patterns with smart matching
• 💬 Conversational Memory: Context-aware responses with chat history
• 🛠️ Tool Integration: Native PTY-based support for penetration testing and web scanning workflows
• 📊 Learning Capability: Feedback loop for continuous improvement via training data collection

🎯 Operating Modes

1. Command Translator Mode

Transform natural language into precise shell commands.

> find all files larger than 100MB in my home directory
→ find ~ -type f -size +100M

2. AI Assistant Mode

Conversational partner for complex command-line tasks with explanations and guidance.

You: How can I check which processes are using the most memory?
Assistant: On Linux, you can use the 'ps' command combined with 'sort':

    ps aux --sort=-%mem | head -n 10

This lists all running processes, sorts them by memory usage in descending
order, and shows the top 10.

3. Metasploit Assistant Mode

Your personal cybersecurity expert with direct msfconsole integration via a pseudoterminal session. Type regular msfconsole commands as usual; prefix a line with ? to ask the AI for guidance.

msf6 > hosts

? search for Log4j exploits
Assistant: You can search for Log4j exploits using the 'search' command:

    search cve:2021-44228

Would you like me to run this command for you?

4. Wapiti Assistant Mode

AI-guided web application security scanning via a Bash session with wapiti available. Prefix prompts with ? to get AI-generated scan commands.

$ ? scan example.com for XSS vulnerabilities
Assistant: To scan for XSS vulnerabilities, run:

    wapiti -u http://example.com -m xss --scope domain

🚀 Quick Start

Prerequisites

• Python 3.9+
• Metasploit Framework (optional, for Metasploit mode)
• Wapiti (optional, for Wapiti mode — pip install wapiti3 or sudo apt install wapiti)
• Ollama (optional, for local LLMs)

Installation

Option 1: From Source (Recommended)

# Clone the repository
git clone https://github.com/GizzZmo/Ai_shell.git
cd Ai_shell

# Install dependencies
pip install -r requirements.txt

# Install the package
pip install -e .

Option 2: Using Setup Scripts

Linux/Mac:

chmod +x install.sh
./install.sh

Windows:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
.\install.ps1

Configuration

1. Copy the example configuration:

   cp config.yaml.example config.yaml
   

2. Set your API key (for Gemini):

   export GEMINI_API_KEY="your_api_key_here"
   

3. For local LLMs, install Ollama:

   # Install Ollama (Linux)
   curl -fsSL https://ollama.ai/install.sh | sh
   
   # Pull a model
   ollama pull llama3
   

Usage

# Interactive mode selection
ai-shell

# Direct modes
ai-shell --mode translator
ai-shell --mode assistant
ai-shell --mode metasploit
ai-shell --mode wapiti

# Specify provider
ai-shell --provider local
ai-shell --provider gemini --api-key your_key

# Use custom config
ai-shell --config myconfig.yaml

# Adjust safety and logging
ai-shell --no-confirmation
ai-shell --log-level DEBUG

For a full CLI reference and mode-by-mode walkthrough, see USAGE.md.

📖 Documentation

Browse focused guides: - Usage Guide — CLI flags, modes, and provider selection - Configuration Guide — config structure, profiles, and templates - Architecture Overview — component and data-flow diagrams - Examples & Tutorials — practical prompts and scripts - Troubleshooting — common fixes and debugging tips

🔧 Development

Project Structure

Ai_shell/
├── ai_shell/           # Main package
│   ├── __init__.py     # Package metadata and version
│   ├── main.py         # Application entry point and mode loops
│   ├── config.py       # Configuration management (YAML + env vars)
│   ├── llm.py          # LLM provider integrations and system prompts
│   ├── executor.py     # Command execution, security, and training logger
│   └── ui.py           # Terminal colors and formatting utilities
├── tests/              # Test suite
├── docs/               # Focused documentation guides
├── config.yaml.example # Example configuration file
├── install.sh          # Linux/Mac installer
├── install.ps1         # Windows installer
├── setup.py            # Package setup
└── requirements.txt    # Runtime dependencies

Testing

# Install development dependencies
pip install pytest pytest-cov black flake8

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=ai_shell

Code Style

# Format code
black ai_shell/ tests/

# Check style
flake8 ai_shell/ tests/

🔒 Security

• API Keys: Store securely using environment variables; never commit them to source control
• Command Review: Always review AI-generated commands before execution
• Confirmation Prompts: Enabled by default; use --no-confirmation only in trusted environments
• Dangerous Command Blocking: Configurable list of patterns blocked before execution
• Local LLMs: Consider Ollama for sensitive or air-gapped environments

See SECURITY.md for the full security policy and responsible disclosure process.

🔄 CI/CD & Workflow System

AI Shell uses a comprehensive GitHub Actions workflow system to ensure code quality, security, and reliability:

🛠️ Automated Workflows

Continuous Integration (CI)

• ✅ Multi-OS Testing: Tests run on Ubuntu, Windows, and macOS
• ✅ Python Versions: Supports Python 3.9, 3.10, 3.11, and 3.12
• ✅ Code Quality: Automated linting with flake8 and formatting checks with black
• ✅ Test Coverage: pytest with coverage reporting to Codecov
• ✅ Package Installation: Validates the package can be installed and used

Security Scanning

• 🔒 CodeQL Analysis: Advanced code security scanning with extended queries
• 🔒 Dependency Scanning: Automated vulnerability checks using Safety
• 🔒 Secrets Detection: Trivy scans for exposed secrets in the codebase
• 🔒 License Compliance: Verifies all dependencies use compatible licenses
• 🔒 Scheduled Scans: Daily security checks to catch new vulnerabilities

Documentation

• 📖 Markdown Validation: Ensures all documentation is syntactically correct
• 📖 Link Checking: Validates internal and external links
• 📖 Automated Deployment: Builds and deploys docs to GitHub Pages with MkDocs

Performance Monitoring

• ⚡ Benchmark Tests: Measures performance of core components
• ⚡ Memory Profiling: Tracks memory usage and detects leaks
• ⚡ Weekly Runs: Regular performance regression testing

Release Automation

• 🚀 Automated Releases: Tag-based releases to GitHub and PyPI
• 🚀 Changelog Generation: Automatic changelog from git commits
• 🚀 Package Building: Builds and validates distribution packages
• 🚀 Pre-release Support: Handles alpha, beta, and RC releases

Smart Automation

• 🏷️ Auto-labeling: Automatically labels issues and PRs based on content
• 🏷️ Size Detection: Labels PRs by change size (XS, S, M, L, XL)
• 📊 Status Dashboard: Daily workflow status reports and repository statistics

📊 Workflow Status

Check our Workflow Status Dashboard for real-time status of all workflows, or view the Actions tab for detailed run history.

🔧 Running Workflows Locally

You can run tests and checks locally before pushing:

# Run tests
python -m pytest tests/ -v --cov=ai_shell

# Check code style
flake8 ai_shell/ tests/
black --check ai_shell/ tests/

# Run security checks
pip install safety
safety check

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Steps

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Make your changes with tests
4. Submit a pull request

📄 License

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

🙏 Acknowledgments

• Google Gemini for powerful language model capabilities
• Ollama community for local LLM support
• Metasploit Framework for penetration testing integration
• Wapiti for web application security scanning

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

⚠️ Disclaimer: AI Shell executes system commands. Always review commands before execution and use appropriate security measures. The developers are not responsible for any damage caused by misuse of this tool.