How 404cisco/pain-x works
Project type and purpose
• PAIN-X is a Python-based, AI-powered command-line assistant.
• Purpose: receive natural-language commands on Linux/Windows, suggest safe shell commands via Google Gemini API, optionally execute them, and log history.
File structure
• Top‐level files:
• pain-x.py – the CLI entry‐point (handles user I/O, mode selection)
• suggester.py – core logic for building prompts, calling Gemini, risk assessment, formatting suggestions
• .env – configuration file for GEMINI_API_KEY (dotenv)
• history.log – persistent command history log
• README.md – documentation
• No separate frontend/backend dirs – it’s a single‐process CLI tool with distinct internal modules.
README for additional insights
• External dependency: Google Gemini API
• Features: quick vs interactive modes, risk checking, clipboard integration, logging
• Cross‐platform support implies abstraction over OS shell execution.
1. CLI Interface (pain-x.py)
2. Suggestion Engine (suggester.py)
3. Risk Assessment module (part of suggester.py)
4. Execution Module (shell runner / subprocess calls)
5. Logger (history.log writer)
6. Config Manager (.env reader via python-dotenv)
7. Clipboard Integrator (xclip on Linux / Windows clipboard API)
8. External AI Service (Google Gemini API)
• User → CLI Interface
• CLI Interface → Config Manager (load API key)
• CLI Interface → Suggestion Engine (pass user input + mode)
• Suggestion Engine ↔ Google Gemini API (send prompt, receive suggestions)
• Suggestion Engine → Risk Assessment module → annotate suggestions
• CLI Interface → Execution Module (if quick mode or user confirms interactive suggestion)
• Execution Module → OS Shell
• Execution Module → Logger (append to history.log)
• CLI Interface → Clipboard Integrator (on copy command)
• All modules → Log successes/errors to history.log
c. Architectural patterns & design principles:
• Modular single-process architecture
• Separation of concerns: I/O (CLI) vs AI logic vs execution vs logging
• Dependency injection for API key and OS calls
• Pluggable modes (quick vs interactive)
d. Key technologies/frameworks:
• Python 3
• python-dotenv (.env)
• Google Gemini API (1.5 Flash)
• subprocess (shell execution)
• xclip / OS clipboard APIs
• File I/O for history.log