MechaCMDHelp - AI Linux Command Assistant

An intelligent command-line assistant that converts natural language into Linux commands using AI. Instead of remembering complex command syntax, just describe what you want to do in plain English.

Important Warning: This tool uses AI which may occasionally suggest incorrect or potentially harmful commands. Always review suggestions carefully before executing them. The built-in safety system helps catch dangerous commands, but you should still verify each suggestion makes sense for your intended task.

What It Does

• Natural Language Input: Type "create a file called test.txt" instead of remembering touch test.txt
• Smart Suggestions: AI understands context and suggests appropriate commands
• Safety First: Warns you before running potentially dangerous commands like rm -rf
• Context Aware: Remembers your current directory and previous commands
• Command History: Navigate previous inputs with arrow keys
• Offline Operation: Runs completely offline after initial setup

Use Cases

Perfect for:

• Learning Linux: Great for beginners who don't know command syntax yet
• Quick Tasks: Faster than looking up command documentation
• Complex Operations: Handles multi-step commands and file operations
• System Administration: Helps with common admin tasks (with safety warnings)

Safety Features

• Destructive Command Detection: Automatically identifies risky commands
• Double Confirmation: Asks twice before running dangerous operations
• Sudo Restrictions: Only allows sudo for package management by default
• Command Sanitization: Removes unnecessary wrappers and fixes common issues
• User Override: You can always type commands manually if AI suggestions aren't right

Requirements

• Linux
• Python 3.8+
• 2GB free space
• Internet (for setup only)

Setup

1. Clone the repository:

   git clone <repository-url>
   cd linux-command-agent

2. Run the setup script:

   chmod +x setup.sh
   ./setup.sh

3. Start using:

   mechacmd

What the Setup Does

The setup script automatically handles everything for you:

1. Installs Ollama - The AI model runtime (if not already installed)
2. Downloads AI Model - Gets the specialized Linux command model (~1.2GB)
3. Sets up Python Environment - Creates a virtual environment in ~/.local/share/mechacmd/
4. Installs System Command - Copies files to ~/.local/share/mechacmd/ and creates a launcher at ~/.local/bin/mechacmd
5. Updates PATH - Adds ~/.local/bin to your PATH in ~/.bashrc (if not already there)

After setup completes, run mechacmd from anywhere (after restarting terminal or running source ~/.bashrc)

How to Use

1. Start the assistant: mechacmd
2. Describe what you want: Type in plain English (e.g., "list all files", "find python files")
3. Review the suggestion: The AI will suggest a command
4. Execute or modify: Press Enter to run, type an alternative, or 'n' to cancel
5. Exit when done: Type :q to quit

Example

> create a file called test.txt
Suggested command: touch test.txt
Execute this command? (y/N) y

> show me all files including hidden ones
Suggested command: ls -la
Execute this command? (y/N) y

> delete everything in this folder
Suggested command: rm -rf *
Warning: This command appears potentially destructive.
Execute this command? (y/N) n
Command not executed.

Troubleshooting

If setup fails:

• Start Ollama manually: ollama serve (in another terminal)
• Check internet connection and free disk space
• Re-run: ./setup.sh

If commands seem wrong:

• Be more specific in your requests
• Check if Ollama is running: ps aux | grep ollama
• Restart the session (type :q and start again)

Important Reminders

Always verify commands before running them - AI can make mistakes or misunderstand your request

Start with safe commands - Test with simple operations like ls or pwd before trying complex tasks

Use in test environments first - Try the tool in a safe directory or virtual machine before using on important data

Have backups - Make sure important files are backed up before running file operations

The AI is trained on Linux commands but may not always understand the full context of your system or intentions. Use your judgment!