AI-Powered Windows Diagnostic & Self-Healing Tool
SuperDiagnosticTool is an intelligent system diagnostic utility that combines real-time hardware telemetry with Google Gemini AI to analyze, diagnose, and automatically remediate Windows system issues. Built with a safety-first architecture, it provides production-grade diagnostics for any Windows configuration.
Main interface showing scan mode selection and problem description input
- Dynamic Scaling: Automatically adapts to any CPU configuration (1-128+ cores)
- Hardware-Agnostic Logic: Works seamlessly on legacy systems (Intel Pentium) to high-end workstations (AMD Threadripper, Intel Xeon)
- Graceful Fallbacks: Safe handling of unsupported features (CPU frequency, battery detection, swap memory)
- Low-Spec Optimized: Lightweight execution prevents system lags even on resource-constrained hardware
- Google Gemini Integration: Advanced AI-powered system analysis and diagnostics
- Context-Aware Recommendations: Correlates user-reported issues with system telemetry
- Security Auditing: Scans for suspicious processes, resource leaks, and potential malware
- Post-Fix Verification: Generates completion reports showing what was fixed vs. what requires manual attention
Production-Grade Security (85%)
- Knowledge Base Matching: Validates AI solutions against 5 tested, known solutions with success rates
- Dry-Run Simulation: Preview all changes before execution (services, files, registry)
- Multi-Level Script Validation: Blacklist, whitelist, and risk scoring (0-100)
- System Restore Points: Automatic restore point creation before any modifications
- Pre/Post Execution Snapshots: Complete system state capture before and after changes
- Change Detection: Automatic tracking of all modifications (services, registry, startup items)
- Rollback Generation: Auto-generated scripts to undo changes if needed
- Execution Logging: Comprehensive logs of all operations
- Admin Privilege Verification: All remediation scripts include elevation checks
- Variable Sanitization: Regex-based escaping prevents errors while preserving
$env:variables - Service Safety Checks: Verifies service existence before operations
- Sandbox Execution: Monitored environment with timeout protection
- Error Handling: Comprehensive try-catch blocks with safeguards
- Performance Metrics: CPU usage (overall + per-core), memory breakdown, top resource consumers
- Network Intelligence: Active interfaces, DNS configuration, Wi-Fi signal strength, connectivity tests
- Security Integrity: Antivirus status, firewall profiles, Windows Update history
- Hardware Health: Disk SMART status, GPU information, battery status (laptops)
- System Services: Startup applications, failed services, critical event logs
- Process Auditing: Identifies suspicious processes based on resource usage and location
- Professional HTML Reports: Dark-themed, responsive diagnostic reports with visual metrics
- Past-Tense Completion Language: Reports use
[FIXED],[CLEANED],[DISABLED]tags to show completed actions - Manual Attention Section: Clearly separates automated fixes from items requiring user intervention
- Timestamped Archives: All reports saved to
AI_Reports/directory for historical tracking
Download SuperDiagnosticTool.exe - Standalone executable (no Python required)
- Windows 10 or Windows 11
- Administrator privileges
- Google Gemini API Key (Get free key)
- Download and run
SuperDiagnosticTool.exe - Enter your Google Gemini API key when prompted
- Describe your system issue
- Select scan mode (Quick/Deep/Complete)
- Review AI analysis and remediation script
- Execute fixes or view detailed HTML report
- Python 3.8 or higher
- pip package manager
pip install psutil google-generativeai richpython super_diagnose_v2.pyOption A: Interactive Input (Recommended for first-time users)
- The tool will prompt you to enter your API key on first run
- Key is saved locally in
gemini.keyfor future use
Option B: Environment Variable
set GEMINI_API_KEY=your_api_key_hereOption C: Manual Key File
Create gemini.key in the same directory:
your_api_key_here
| Mode | Scans | Use Case |
|---|---|---|
| Quick Scan | CPU, RAM, Basic Info | Fast performance check |
| Deep Scan | System, Network, Security, Logs, Bluetooth, Processes | Comprehensive troubleshooting |
| Complete Scan | All of the above + Disk Health, GPU, Startup Apps | Full system audit |
# 1. Run the tool
SuperDiagnosticTool.exe
# 2. Describe your issue
> High CPU usage and slow performance
# 3. Select scan mode
> 3 (Complete System Scan)
# 4. Wait for AI analysis
[Scanning system layers...]
[Processing telemetry logic...]
# 5. Review remediation script
[PowerShell script displayed]
> Execute? (y/n)
# 6. View HTML report
> Open detailed report? (y/n)- Modular design with separate functions for each diagnostic category
- Comprehensive error handling with try-except blocks
- Hardware-agnostic queries with graceful fallbacks
- Professional docstrings and clear variable naming
- Admin privilege verification before execution
- Regex-based variable escaping to prevent syntax errors
- Environment variables (
$env:TEMP,$env:PATH) preserved correctly - Safe service management with existence checks
- Error suppression using
-ErrorAction SilentlyContinue
- Structured prompts for consistent output parsing
- Delimited sections (
[ANALYSIS_START],[FIX_START]) for reliable extraction - Context-aware analysis based on system telemetry
- Past-tense reporting for completed remediation actions
- No Data Collection: All analysis happens locally; only system telemetry is sent to Gemini API
- API Key Security: Keys are stored locally and never committed to version control
- Admin Transparency: User must explicitly approve all remediation scripts
- Non-Destructive: No file deletion or registry modifications without user consent
- Open Source: Full source code available for security auditing
See SECURITY.md for detailed security information.
- Verify your API key is correct and active
- Check for hidden characters or whitespace
- Ensure the key has Gemini API access enabled
- Regenerate key at https://makersuite.google.com/app/apikey
- Right-click the executable and select "Run as Administrator"
- Or allow the UAC prompt when the tool auto-elevates
pip install --upgrade psutil google-generativeai rich- Ensure you're running Windows PowerShell 5.1 or later
- Check that execution policy allows script execution
- Review the script in
AI_Reports/remediation.ps1for errors
The project uses GitHub Actions to automatically build Windows executables when a version tag is pushed:
- Push your changes to the main branch
- Create and push a version tag:
git tag -a v1.0.2 -m "Release notes" && git push origin v1.0.2 - GitHub Actions will automatically build the .exe and create a release
- Download from the Releases page
See RELEASE_PROCESS.md for detailed instructions.
On Windows:
pip install pyinstaller
pip install -r requirements.txt
python build.pyThis creates dist/SuperDiagnosticTool.exe with embedded icon and dependencies.
Note: If you see a "Windows protected your PC" warning, please read TRUST_GUIDE.md for a quick fix or how to permanently whitelist the app.
Note: Building on Linux/Mac will create platform-specific binaries, not Windows .exe files. Use GitHub Actions for official Windows releases.
SuperDiagnosticTool/
├── super_diagnose_v2.py # Main diagnostic script
├── build.py # Build script for creating EXE
├── icon.ico # Application icon
├── .github/workflows/ # GitHub Actions workflows
│ └── release.yml # Automated build and release
├── docs/
│ ├── icon.png # Icon for README
│ └── screenshot_main.png # Main interface screenshot
├── src/ # Source modules
│ ├── safety/ # Safety and validation modules
│ └── security/ # Security features
├── AI_Reports/ # Generated HTML reports
├── README.md # This file
├── RELEASE_PROCESS.md # Release process documentation
├── LICENSE # GPL-3.0 License
├── SECURITY.md # Security documentation
└── .gitignore # Git ignore rules
IMPORTANT: System Modification Warning
This tool generates and executes PowerShell scripts that modify system services, configurations, and settings. While designed with safety-first principles:
- Always review the generated PowerShell script before execution
- Backup critical data before running automated remediation
- Test on non-production systems first if possible
- Understand the changes being made to your system
The author is not responsible for any system damage, data loss, or unintended consequences resulting from the use of this tool. Use at your own risk.
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/improvement) - Commit your changes (
git commit -m 'Add improvement') - Push to the branch (
git push origin feature/improvement) - Open a Pull Request
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
Copyright (C) 2026 GUETTAF HOUSSEM EDDINE
Knight
Electrotechnics Engineering Student
Akli Mohand Oulhadj University, Bouira, Algeria
Email: hossam.guettaf@proton.me
GitHub: @Guettaf-hossam
- Google Gemini AI for intelligent system analysis
- psutil library for cross-platform system monitoring
- Rich library for beautiful terminal output
Version 1.0 | Last Updated: January 2026
Made with dedication by Knight | Akli Mohand Oulhadj University