SuperDiagnosticTool

AI-Powered Windows Diagnostic & Remediation Tool

SuperDiagnosticTool collects real-time hardware telemetry, sends it to the Google Gemini API for analysis, and generates PowerShell remediation scripts to address detected issues. It includes multiple validation layers that a generated script must pass before the user is prompted to execute it.

---

Screenshots

Main interface showing scan mode selection and problem description input

---

Key Features

Universal Hardware Support

• Dynamic Scaling: Automatically adapts to any CPU configuration (1-128+ cores)
• Hardware-Agnostic Logic: Works on legacy systems (Intel Pentium) through high-end workstations (AMD Threadripper, Intel Xeon)
• Graceful Fallbacks: Safe handling of unsupported hardware queries (CPU frequency, battery, swap memory)
• Low-Spec Optimized: Lightweight execution to avoid resource pressure on constrained hardware

Intelligent AI Analysis

• Google Gemini Integration: AI-powered system analysis and diagnostics via the Gemini API
• Context-Aware Recommendations: Correlates user-reported issues with collected system telemetry
• Security Auditing: Scans for suspicious processes, resource leaks, and potential malware indicators
• Post-Fix Verification: Generates completion reports distinguishing automated fixes from items requiring manual attention

Multi-Layer Safety Architecture

Scripts generated by Gemini pass through four sequential checks before the user is asked to approve execution:

Validation Pipeline

• Knowledge Base Matching: Cross-references AI solutions against a set of tested, known-good remediation patterns
• Dry-Run Simulation: Previews all intended changes (services, files, registry) before any modification occurs
• Script Validation (ScriptValidator): Three-level check — blacklist (hard block on destructive patterns), suspicious pattern detection (alias and obfuscation-aware), and risk scoring on a 0-100 scale
• Critical Path Interception (CriticalPathInterceptor): Zero-trust gate that halts any script touching HKLM/HKCU registry keys or System32 paths until the user explicitly confirms

Safety Limits

• System Restore Points: Created automatically before any modification
• Pre/Post Execution Snapshots: Full system state capture to detect and log every change made
• Rollback Generation: Auto-generates a selective rollback script if execution fails
• Execution Logging: Every action logged with timestamps to %TEMP%\superdiagnostic_execution_*.log

PowerShell Execution

• Admin Privilege Verification: Scripts check for elevation before proceeding
• Variable Sanitization: Regex-based escaping preserves $env: variables without syntax errors
• Service Safety Checks: Verifies service existence before any Start/Stop/Set operation
• Monitored Execution: Scripts run via subprocess.run with a hard 5-minute timeout, full stdout/stderr capture, and automatic temp-file cleanup. This is direct host-level execution, not VM or container isolation. The validation layers above are the primary safety boundary.
• Error Handling: PowerShell wrapper includes try/catch/finally blocks with per-line error reporting

Comprehensive System Scanning

• 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 processes with unusual resource usage or file locations

Human-Centric Reporting

• Professional HTML Reports: Dark-themed, responsive diagnostic reports with visual metrics
• Past-Tense Completion Language: Reports use [FIXED], [CLEANED], [DISABLED] tags to reflect completed actions
• Manual Attention Section: Clearly separates automated fixes from items requiring user intervention
• Timestamped Archives: All reports saved to AI_Reports/ for historical tracking

---

Quick Start

Download

Download SuperDiagnosticTool.exe — Standalone executable (no Python required)

The executable is unsigned. Windows SmartScreen will show a warning on first run. See TRUST_GUIDE.md for how to proceed. If you prefer to verify before running, build from source instead.

Requirements

• Windows 10 or Windows 11
• Administrator privileges (required for system telemetry and remediation)
• Google Gemini API Key (Get free key)

First Run

1. Download and run SuperDiagnosticTool.exe
2. Enter your Google Gemini API key when prompted
3. Describe your system issue
4. Select scan mode (Quick / Deep / Complete)
5. Review the AI analysis and the generated remediation script
6. Approve execution or view the detailed HTML report

---

Installation (For Developers)

Prerequisites

• Python 3.8 or higher
• pip package manager

Install Dependencies

Create a virtual environment so the tool's dependencies stay isolated from other Python projects:

python -m venv .venv

Activate it in Windows Command Prompt, then install the dependencies listed by the repository:

.venv\Scripts\activate
pip install -r requirements.txt

In PowerShell, activate the environment with:

.\.venv\Scripts\Activate.ps1

If PowerShell blocks the activation script, open PowerShell as your user and run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once, then try the activation command again.

Run from Source

python super_diagnose_v2.py

To confirm that the source tree and dependencies are ready before starting a scan, run:

python -m compileall src super_diagnose_v2.py

The command should finish without errors. The tool still requires Windows and administrator privileges when it is run, because several diagnostics use PowerShell and protected system information.

---

Usage

API Key Setup

Option A: Interactive Input (recommended for first-time use)

• The tool prompts for an API key on first run
• Key is stored securely via Windows DPAPI (keyring) when available

Option B: Environment Variable Command Prompt:

set GEMINI_API_KEY=your_api_key_here

PowerShell:

$env:GEMINI_API_KEY = "your_api_key_here"

Option C: Manual Key File Create gemini.key in the tool directory:

your_api_key_here

Scan Modes