An intelligent, AI-enhanced terminal shell with advanced features, beautiful theming, and powerful command execution capabilities.
Features β’ Installation β’ Quick Start β’ Documentation β’ Contributing
- Overview
- Key Features
- Preview
- Installation
- Requirements
- Quick Start
- Command-Line Flags
- Interactive Shell Overview
- Built-In Commands
- AI Features
- Explain Last Command System
- Multi-Command Execution Rules
- Themes
- Prompt Styles
- Configuration System
- API Setup
- Error Recovery System
- File Management Capabilities
- System Commands Overview
- Security Notes
- Termux Compatibility Notes
- Linux Compatibility Notes
- Known Limitations
- Project Structure
- Contributing
- License
- Author & Credits
- Community & Support
VritraAI is a next-generation AI-powered terminal shell that combines the power of traditional Unix commands with cutting-edge artificial intelligence. Built from scratch by Alex Butler of Vritra Security Organization, VritraAI transforms your terminal experience with intelligent command explanations, code analysis, project management, and a beautiful, customizable interface.
- π€ AI-Powered Assistance: Get intelligent explanations for commands, code reviews, and project analysis
- π¨ 37 Beautiful Themes: Customize your terminal with professional color schemes
- π¬ 60+ Prompt Styles: Express your personality with creative prompt designs
- π Smart Command Logging: Automatically track and explain system commands
- π‘οΈ Error Recovery: Intelligent error handling with AI-powered suggestions
- π¦ Project Intelligence: Automatic project type detection and dependency management
- π Security Features: Built-in dangerous command warnings and safe mode
- Natural Language AI Assistant: Chat with AI using
ai <prompt>for any question or task - Command Explanation: Understand what any command does with
explain <command>orexplain_last - Code Review & Analysis: Comprehensive AI-powered code review with
review <file|directory> - Security Scanning: AI-powered security vulnerability detection with
security_scan <file|directory> - Code Optimization: Get AI optimization suggestions with
optimize_code <file> - Code Refactoring: AI-powered refactoring suggestions with
refactor <file> <description> - Project Intelligence: Enhanced project type detection, health analysis, and optimization
- Interactive Learning: AI tutoring system with
learn <topic>for any programming concept - Cheat Sheets: Generate command cheatsheets with
cheat <topic> - Content Generation: AI content generation helper with
generate <description> - Documentation Generator: Auto-generate README, docstrings, tutorials, and architecture diagrams
- File/Directory Analysis: AI-powered analysis with
summarize [path]for deep insights
- 37 Color Themes: From dark/light to cyberpunk, matrix, galaxy, and more
- 60+ Prompt Styles: Hacker, pirate, ninja, robot, superhero, and many more
- Customizable Banners: Professional MOTD banners with system stats
- Rich Formatting: Beautiful terminal output with syntax highlighting
- File Management: Create, edit, read, search, and manage files
- Code Formatting: Automatic code formatting with black/autopep8
- Network Tools: Complete network diagnostics and monitoring
- System Monitoring: Real-time system information and performance metrics
- Project Templates: Quick project scaffolding for various frameworks
- Dangerous Command Warnings: Confirmation prompts for risky operations
- Safe Mode: Enhanced protection for critical operations
- Command Validation: Intelligent command validation before execution
- Session Logging: Complete command history and session tracking
Install VritraAI directly from PyPI:
pip install vritraaiFor development or to get the latest features:
# Clone the repository
git clone https://github.com/VritraSecz/VritraAI.git
cd VritraAI
# Install dependencies
pip install -r requirements.txt
# Run directly
python vritraai.py- Python: 3.7+ (3.8+ recommended)
- Operating System: Linux, macOS, or Termux (Android)
- Dependencies: See Requirements section
openai==0.28.0- OpenAI API client for OpenRouter integrationrequests>=2.28.0- HTTP library for API requestsprompt-toolkit>=3.0.0- Advanced terminal UI library
rich>=13.0.0- Rich text and beautiful terminal formatting
pygments>=2.13.0- Syntax highlighting for code displaypsutil>=5.9.0- System and process utilitiesblack>=23.0.0- Python code formatter (forformat_filecommand)autopep8>=2.0.0- Alternative Python code formatter
# Install all dependencies
pip install -r requirements.txt
# Install only core dependencies
pip install openai requests prompt-toolkit rich
# Install with optional features
pip install openai requests prompt-toolkit rich pygments psutil black autopep8# After installation
vritraai
# Or run directly
python vritraai.py# Set up Gemini API (default)
apikey gemini YOUR_GEMINI_API_KEY
# Or set up OpenRouter API
apikey openrouter YOUR_OPENROUTER_API_KEY# Ask AI questions
ai How do I use git rebase?
# Explain last command
ls -la
explain_last
# Review code
review myfile.py
# Learn something new
learn "bash loops"# Change theme
theme cyberpunk
# Change prompt style
prompt hacker
# View all options
theme
promptVritraAI supports the following command-line flags:
| Flag | Long Form | Description |
|---|---|---|
-h |
--help |
Show help message and exit |
-v |
--version |
Show version information and exit |
-i |
--interactive |
Launch in interactive mode (default) |
# Show help
python vritraai.py -h
python vritraai.py --help
# Show version
python vritraai.py -v
python vritraai.py --version
# Launch interactive mode (default)
python vritraai.py -i
python vritraai.py --interactive
# Launch without flags (same as -i)
python vritraai.pyNote: Only one flag can be used at a time. Using multiple flags will result in an error.
VritraAI provides a powerful interactive shell with:
- Command History: Full command history with arrow key navigation
- Auto-completion: Intelligent command and path completion
- Syntax Highlighting: Beautiful code syntax highlighting
- Rich Output: Formatted tables, panels, and colored output
- Session Tracking: Complete session logging and analytics
- Tab Completion: Press
Tabto autocomplete commands and paths - History Navigation: Use
β/βarrows to navigate command history - Multi-line Commands: Use
\for line continuation - Command Chaining: Use
;or&&to chain commands - Pipes: Full support for Unix pipes (
|)
VritraAI includes 100+ built-in commands. Here are the top 20 most commonly used commands:
| Command | Description |
|---|---|
ai <prompt> |
Natural language AI assistant |
explain_last |
Explain the last executed command |
review <file|directory> |
AI-powered code review |
ls [path] |
Colored directory listing |
read_file <file> |
Read file with syntax highlighting |
edit_file <file> |
Open file in editor or create new |
cd <directory> |
Change directory |
theme [name] |
Change color theme (37 available) |
prompt [style] |
Change prompt style (60+ available) |
config |
Show current configuration |
apikey <provider> <key> |
Set API key (gemini/openrouter) |
model [list|set|search] |
Manage AI models |
project_type |
Detect project type automatically |
sys_info |
Comprehensive system information |
search_file <pattern> [path] |
Search for files by name |
find_files <pattern> [path] |
Advanced file search with regex |
summarize [path] |
AI-powered directory/file analysis |
learn <topic> |
Interactive AI tutoring |
doc readme |
Generate README.md for project |
history |
View command history |
π‘ Note: For a complete list of all commands, use the
helpcommand in VritraAI or visit vritraai.vritrasec.com/ for detailed documentation.
VritraAI can explain any system command you execute:
# Execute a command
ls -lah /usr/bin
# Get AI explanation
explain_lastThe AI will provide:
- What the command did
- Why it succeeded or failed
- Optimization tips
- Related commands
- Fix suggestions (if errors occurred)
Get intelligent code analysis:
review myfile.pyFeatures:
- Code quality assessment
- Security vulnerability detection
- Performance optimization suggestions
- Best practices recommendations
- Bug detection
Automatic project analysis:
# Detect project type
project_type
# Check dependencies
dependencies_check
# Analyze project health
project_healthInteractive learning:
learn "bash loops"
learn "git rebase"
learn "python decorators"Provides:
- Brief explanations
- Common use cases
- Practical examples
- Best practices
- Common mistakes to avoid
The explain_last command provides intelligent analysis of your last executed command.
- Command Logging: System commands and whitelisted built-ins are automatically logged
- Output Capture: Command output is captured including Rich-formatted output
- AI Analysis: AI analyzes the command, output, and context
- Detailed Explanation: Provides comprehensive explanation with fixes and recommendations
The following built-in commands are automatically logged:
ls,dir,search_file,find_fileshash,validate,formatsearch_regex,cd,sys_infodisk_usage,env,path,whichuptime,memory,processestime,calc,templateencode,decode
# Execute any system command
grep -r "pattern" /path/to/search
# Get explanation
explain_last- β Automatic command logging
- β Rich output capture
- β Context-aware analysis
- β Error diagnosis
- β Fix suggestions
- β Optimization tips
VritraAI supports command chaining with strict validation for safety.
;- Sequential execution (always executes)&&- Conditional execution (executes if previous succeeds)
- Only System Commands: Multi-command sequences only allow system commands and whitelisted built-ins
- No AI Commands: AI commands must be executed separately
- Validation: Each command in the sequence is validated before execution
- Labeled Output: Each command's output is labeled for clarity
File Operations:
ls,dir,read_file,search_file,mkdir,create_dirfind_files,compare,diff,hash,validate,format,tree
System Commands:
cd,clear,exit,help,sys_info,disk_usageenv,path,which,uptime,memory,processestime,calc,config,template,theme,promptencode,decode,network,analyze_system
API/Model Management:
apikey,api_base,model
# Valid: System commands
ls -la; cd /tmp; pwd
# Valid: Mixed system and built-ins
ls; sys_info; memory
# Invalid: AI commands (must be separate)
ls; ai "what is this?" # β Error: AI command detected
# Valid: Pipes work normally
ls -la | grep ".py"VritraAI includes 37 professionally designed color themes. Here are the top 10 most popular themes:
| Theme | Description |
|---|---|
| dark | Default dark terminal theme |
| light | Light theme with classic colors |
| matrix | Matrix-style green hacker terminal |
| cyberpunk | High-contrast cyberpunk palette |
| galaxy | Space/galaxy purples and blues |
| ocean | Cool blue ocean-inspired theme |
| neon | Bright neon accents for high contrast |
| retro | Retro neon green-on-black look |
| hacker_green | Aggressive hacker green-on-black |
| synthwave | 80s synthwave neon palette |
π‘ Note: VritraAI includes 27 more themes! Use
themecommand to see all available themes, or visit vritraai.vritrasec.com/ for the complete list.
# List all themes
theme
# Change theme
theme cyberpunk
# Reset to default
theme resetVritraAI offers 60+ creative prompt styles to personalize your terminal:
- hacker - Hacker-style multi-line:
βββ(userγΏvritraai)-[path]\nββ$ - matrix - Matrix style:
wake up, neo:// path $ - cyberpunk - Cyberpunk style:
βΆ path β - ninja - Ninja style:
β‘ path β‘ - pirate - Pirate style:
π΄ββ οΈ [CAPTAIN] @ path β - superhero - Superhero style:
π¦Έ [HERO] :: path >> - robot - Robot style:
π€ [SYSTEM] :: path >> - alien - Alien style:
π½ [PROBE] ~~ path πΈ
Classic Styles:
classic,minimal,modern,powerline,git,elegant
Tech Styles:
hacker,cyberpunk,matrix,code_matrix,terminal_classic
Fun Styles:
ninja,pirate,superhero,robot,alien,magicalmedieval,western,steampunk,gaming
Professional Styles:
corporate,professional,elegant,minimal_zen
Nature Styles:
space,fire,water,earth,airmountain,jungle,desert,arctic
And many more!
π‘ Note: VritraAI includes 60+ prompt styles! Use
promptcommand to see all available styles, or visit vritraai.vritrasec.com/ for the complete list.
# List all prompt styles
prompt
# Change prompt style
prompt hacker
# Reset to default
prompt resetVritraAI uses a unified configuration system with automatic persistence.
- Config Directory:
~/.config-vritrasecz/vritraai/ - Config File:
~/.config-vritrasecz/vritraai/config.json - History File:
~/.config-vritrasecz/vritraai/history - Session Log:
~/.config-vritrasecz/vritraai/session.log - Last Command Log:
~/.config-vritrasecz/vritraai/lastcmd.log - Learning Notes:
~/.config-vritrasecz/vritraai/learning.md - Version Info:
~/.config-vritrasecz/vritraai/vritraai-version.json - Config Backup:
~/.config-vritrasecz/vritraai/config.json.backup(automatic backup)
# Show current configuration
configConfiguration is automatically saved when you:
- Change themes (
theme <name>) - Change prompt styles (
prompt <style>) - Set API keys (
apikey <provider> <key>) - Switch API bases (
api_base <provider>) - Change models (
model set <id>)
VritraAI supports two AI providers: Gemini (default) and OpenRouter.
- Get API Key: Visit Google AI Studio
- Set API Key:
apikey gemini YOUR_GEMINI_API_KEY
- Available Models:
gf1- Gemini 2.0 Flash (default)gf2- Gemini 2.5 Flashgf3- Gemini 2.5 Flash Litegf4- Gemini Flash Latestgp1- Gemini 2.5 Pro
- Get API Key: Visit OpenRouter
- Set API Key:
apikey openrouter YOUR_OPENROUTER_API_KEY
- Switch API Base:
api_base openrouter
- Available Models: 20+ models including:
- DeepSeek (Chat, Prover)
- Meta LLaMA (3.3, 3.1, 3.2)
- Mistral AI (7B, Nemo, Pixtral)
- Google Gemma
- OpenAI GPT
- Qwen, Z-AI, and more
# List available models
model list
# Set model
model set gf1
# Search models
model search flash# Set Gemini API key
apikey gemini YOUR_KEY
# Set OpenRouter API key
apikey openrouter YOUR_KEY
# View API key help
apikey helpVritraAI includes an intelligent error recovery system with AI-powered suggestions.
- Automatic Error Detection: Catches exceptions and errors automatically
- Context Analysis: Analyzes error context, traceback, and code
- AI-Powered Suggestions: Provides specific fix suggestions
- Interactive Recovery: Menu-driven error recovery options
- Retry Mechanism: Automatic retry with fixes applied
When an error occurs, you'll see:
- Error Details: Full error message and traceback
- Context Information: File, line number, and code snippet
- AI Suggestions: Specific fix recommendations
- Recovery Options:
- Apply suggested fix
- Retry operation
- Skip and continue
- Get more help
# If an error occurs during file operation
edit_file nonexistent.py
# VritraAI will:
# 1. Detect the error
# 2. Analyze the context
# 3. Suggest fixes (e.g., "File doesn't exist. Create it?")
# 4. Offer recovery optionsVritraAI provides comprehensive file management features:
- Read Files: Syntax-highlighted file viewing
- Edit Files: Open in default editor or create new files
- Create Files: Quick file creation with templates
- Search Files: Pattern-based and regex file search
- Compare Files: Side-by-side file comparison
- Format Files: Automatic code formatting
- Hash Files: Calculate file checksums
Quick project scaffolding:
# Create Python template
template python my_script.py
# Create Bash template
template bash script.sh
# Create HTML template
template html index.html
# Create README template
template readme README.md# Search by pattern
search_file "*.py"
# Advanced search
find_files "test.*\.py$"
# Regex search
search_regex "def.*test" *.pyVritraAI enhances standard system commands with additional features:
ls: Colored output with file type indicatorscd: Smart directory navigation with error recoverygrep: Highlighted search resultscat: Syntax-highlighted file display
# Comprehensive system info
sys_info
# Disk usage
disk_usage /home
# Memory stats
memory
# Process list
processes
# System uptime
uptime# View environment variable
env PATH
# Set environment variable
env MY_VAR "value"
# PATH management
path add /new/path- Dangerous Command Warnings: Confirmation prompts for risky operations
- Command Validation: Pre-execution validation
- Safe Mode: Enhanced protection mode
- Session Logging: Complete audit trail
The following commands require confirmation:
rm -rf,rm -rfv,rm *dd,mkfs,fdiskshutdown,reboot,haltchmod 777,chown -Rsudo rm,sudo dd> /dev/null,truncate,shred
- API keys are stored in
~/.config-vritrasecz/vritraai/config.json - File permissions are automatically set to user-only access
- Never share your API keys or config files
- Review commands before execution
- Use safe mode for critical operations
- Keep API keys secure
- Regularly review session logs
- Don't execute untrusted commands
VritraAI is fully compatible with Termux on Android.
- β Full command support
- β File system access
- β Network tools
- β AI features
- β Theme customization
# Update packages
pkg update && pkg upgrade
# Install Python
pkg install python
# Install pip packages
pip install vritraai
# Or clone and install
git clone https://github.com/VritraSecz/VritraAI.git
cd VritraAI
pip install -r requirements.txt- Some system commands may have limited functionality
- File permissions follow Android security model
- Network tools work within Termux environment
- All AI features are fully functional
VritraAI is designed primarily for Linux systems.
- β Ubuntu/Debian
- β Fedora/RHEL/CentOS
- β Arch Linux
- β openSUSE
- β Other Linux distributions
- Full system command support
- Complete file system access
- Network diagnostics
- Process management
- System monitoring
# Using pip (recommended)
pip install vritraai
# Or from source
git clone https://github.com/VritraSecz/VritraAI.git
cd VritraAI
pip install -r requirements.txtMost Linux distributions include Python 3.7+ by default. Install additional dependencies as needed:
# Ubuntu/Debian
sudo apt-get install python3-pip python3-venv
# Fedora
sudo dnf install python3-pip
# Arch Linux
sudo pacman -S python-pip- Windows Support: Limited Windows support (primarily Linux/Termux)
- Multi-line Commands: Some complex multi-line commands may need adjustment
- Interactive Commands: Some interactive commands may not work perfectly
- API Rate Limits: Subject to API provider rate limits
- Large Files: Very large files may take time to process
- Use Linux or Termux for best experience
- Break complex commands into simpler ones
- Use non-interactive alternatives when possible
- Monitor API usage to avoid rate limits
- Use
headortailfor large files
VritraAI/
βββ vritraai.py # Main application file
βββ config_manager.py # Unified configuration system
βββ config.py # Legacy configuration (fallback)
βββ requirements.txt # Python dependencies
βββ setup.py # PyPI package setup script
βββ pyproject.toml # Modern Python project configuration
βββ MANIFEST.in # Package manifest for PyPI
βββ README.md # This file
βββ LICENSE # MIT License file
βββ CHANGELOG.md # Version history and changelog
User Configuration Directory:
~/.config-vritrasecz/vritraai/
βββ config.json # Configuration file
βββ config.json.backup # Automatic config backup
βββ .config.lock # Configuration lock file (internal)
βββ history # Command history
βββ session.log # Session log
βββ lastcmd.log # Last command log
βββ learning.md # Learning notes (from `learn` command)
βββ vritraai-version.json # Version information file
vritraai.py: Main application (13,820+ lines)config_manager.py: Configuration management systemconfig.py: Legacy configuration fallbackrequirements.txt: All project dependenciessetup.py: PyPI package setup scriptpyproject.toml: Modern Python project configuration (PEP 518)MANIFEST.in: Package manifest for including files in PyPI distributionLICENSE: MIT License fileCHANGELOG.md: Version history and changelog documenting all notable changes
We welcome contributions to VritraAI! This is an open-source project built from scratch, and your contributions help make it better.
-
Fork the Repository
git clone https://github.com/VritraSecz/VritraAI.git cd VritraAI -
Create a Branch
git checkout -b feature/your-feature-name
-
Make Your Changes
- Follow existing code style
- Add comments for complex logic
- Test your changes thoroughly
-
Commit Your Changes
git commit -m "Add: Description of your changes" -
Push to Your Fork
git push origin feature/your-feature-name
-
Create a Pull Request
- Go to the GitHub repository
- Click "New Pull Request"
- Describe your changes clearly
- β Follow PEP 8 style guidelines
- β Add docstrings to new functions
- β Test your changes before submitting
- β Update documentation if needed (see vritraai.vritrasec.com/)
- β Keep commits focused and atomic
- π Bug fixes
- β¨ New features
- π Documentation improvements (vritraai.vritrasec.com/)
- π¨ New themes or prompt styles
- π§ Performance optimizations
- π§ͺ Test coverage
- π Translations
# Clone repository
git clone https://github.com/VritraSecz/VritraAI.git
cd VritraAI
# Create virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Run in development mode
python vritraai.pyThis project is licensed under the MIT License.
MIT License
Copyright (c) 2024 Alex Butler, Vritra Security Organization
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Alex Butler
Owner, Vritra Security Organization
- Original Project: Built from scratch by Alex Butler
- Organization: Vritra Security Organization
- Version: v0.30.1
- Status: Active Development
- Built with β€οΈ from scratch
- Inspired by modern terminal tools and AI assistants
- Thanks to all contributors and users
- GitHub: @VritraSecz
- Repository: VritraAI
- π Documentation: Detailed documentation available at vritraai.vritrasec.com/
- π Inline Help: Use
helpcommand in VritraAI for comprehensive command reference - π Bug Reports: GitHub Issues
- π‘ Feature Requests: GitHub Issues
- π€ Contributions: See Contributing section
- GitHub Repository: VritraSecz/VritraAI
- Documentation Website: vritraai.vritrasec.com/
- Main Website: vritrasec.com
- Contact: link.vritrasec.com
- Email: [email protected]
- π§ Email: [email protected]
- π Contact Form: link.vritrasec.com
- π GitHub Issues: For bug reports and feature requests
- π Documentation: vritraai.vritrasec.com/ for detailed guides
We value your feedback! Please:
- β Star the repository if you find it useful
- π Report bugs with detailed information
- π‘ Suggest new features
- π Improve documentation (vritraai.vritrasec.com/)
- π€ Contribute code
Made with β€οΈ by Alex Butler | Vritra Security Organization
