GenAIShell is a production-quality, modular, and security-hardened terminal assistant. It utilizes Python and the Gemini API to translate natural language prompts into precise terminal actions, executing them securely with strict sandboxing and real-time user-in-the-loop confirmations.
- Natural Language to Shell Execution: Translate conversational intents into execution scripts (cross-platform compatible on Windows PowerShell, macOS, and Linux).
- Strict Command Sandboxing & Filtering: Blocks malicious destructive actions (e.g. fork bombs, system formatting, raw disk writes) via custom security guardrails.
- Immersive Interactive Shell: Rich interactive shell loop incorporating formatted Markdown panels and command feedback.
- Agent Loop (ReAct Plan Execution): Multi-step reasoning loops allowing the assistant to chain execution goals sequentially (e.g., locate file, copy file, commit to git).
- Local Persistent Memory: Transactional SQLite session tracking to maintain conversational state across system restarts.
- Local NumPy Vector Store: Lightweight semantic database for RAG capabilities without native compilation tool burdens.
- Extensible Plugin Registry: Single-decorator mapping of Python functions to Gemini tools.
[User Input]
│
▼
┌───────────────────┐
│ Typer CLI Layer │
└─────────┬─────────┘
│
▼
┌───────────────────────────────┐
│ Core ReAct Agent Orchestrator │
└───────────────┬───────────────┘
│
┌──────────────────────┼──────────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌───────────────┐
│ SQLite Memory│ │ Vector RAG │ │ Plugin system │
└──────────────┘ └──────────────┘ └───────┬───────┘
│
▼
┌───────────────┐
│ Security Check│
└───────┬───────┘
│
[Safe] ▼ [Risky]
┌────────┴────────┐
▼ ▼
┌──────────────┐ ┌──────────────┐
│ Executor Run │ │ User Prompt │
└──────────────┘ └──────────────┘
terminal_assistant/
│
├── config/
│ └── settings.py # Configuration management via Pydantic (BaseSettings)
│
├── security/
│ └── guardrails.py # Strict command blocking, classification rules, and escapes
│
├── core/
│ ├── orchestrator.py # LLM connection helper and vector embedding generation
│ ├── executor.py # Secure subprocess launcher (with timeout support)
│ └── agent_loop.py # ReAct conversational orchestrator loop
│
├── storage/
│ ├── memory.py # Persists session history, commands, and schemas via SQLite
│ └── vector_store.py # Local NumPy-optimized cosine similarity database
│
├── tools/
│ ├── base.py # Single-decorator system tool registration controller
│ ├── file_tools.py # Search, summary, and CRUD operations
│ ├── git_tools.py # Version-control commit utilities
│ ├── system_tools.py # Process monitors and port terminators
│ └── search_tools.py # Local semantic RAG search
│
├── cli/
│ └── main.py # Gorgeous interactive Typer console using Rich formatting
│
├── utils/
│ └── logging.py # Configured system file & Console logging
│
├── requirements.txt # Production-level python packages
├── Dockerfile # Multi-stage containerized execution runner
├── .env.example # Template for API credentials
├── main.py # Entry Point
└── README.md # System documentation
- Python 3.11+ installed on the host machine.
- A Gemini API Key (obtainable via Google AI Studio).
# Clone the repository
git clone <repository-url>
cd Terminal_based-project
# Initialize virtual environment
python -m venv venv
source venv/bin/activate # On Windows use: venv\Scripts\activate
# Install requirements
pip install -r requirements.txtCreate a .env file in the root directory (based on .env.example):
GEMINI_API_KEY=AIzaSy...your_gemini_key
SAFE_MODE_ENABLED=True
MAX_SHELL_TIMEOUT=30
LOG_LEVEL=INFOLaunch the beautiful continuous interactive loop where the assistant maintains session context:
python main.py interactiveExecute a quick natural language task directly and terminate immediately:
python main.py ask "Create a folder named backups and list files in it"Add text or documentation files to the local semantic index for context queries:
python main.py docs-index "/path/to/documentation.txt" --category "FastAPI"Flush both the SQLite session files and vector store index schemas:
python main.py clear-historySecurity is paramount when allowing an LLM to interact with local terminal subprocesses:
- Regex Command Guardrails: Checks incoming shell calls against critical system destruction patterns (
rm -rf /,Format-Volume, fork bombs, raw dd block copying). Blocked items are instantly halted with security error alerts. - Classification Engine: Sorts operations into:
- Blocked: Permanently intercepted.
- Risky: Commands containing staging write redirection (
>), user escalations (sudo,runas), process terminators (kill,Stop-Process), or file deletions. - Safe: Safe reads or listings.
- User-in-the-Loop Interception: Risky actions block the execution pipeline, popping up a gorgeous yellow alert panel showing the target action and reasoning, prompting the user for an interactive
[Y/N]approval check. - Subprocess Runaway Timeouts: Enforces execution timeouts (defaults to
30s) inside the core asynchronous executor. If exceeded, the subshell process and all of its spawned child trees are terminated cleanly (using process group kills on Windows/Linux) to prevent runaway resource leaks.
To ensure the terminal assistant has absolutely zero risk of modifying your host machine, you can run it inside a fully isolated Docker container:
# 1. Build sandboxed Docker container
docker build -t genai-shell .
# 2. Run container in interactive mode mounting local data persistent folder
docker run -it -e GEMINI_API_KEY="AIzaSy..." -v "$(pwd)/data:/app/data" genai-shell interactive