🔬 SystemLens

An intelligent system explainer that converts raw metrics into human-readable insights.

CreatedBYNJ5.0

SystemLens doesn't just show numbers — it tells you why your system is slow, what is responsible, and what you should do about it. It acts like a senior engineer explaining system behavior to a beginner.

Works on Linux, macOS, and Windows.

🚀 Quick Start

# Run instantly with npx (no install needed)
npx systemlens

# Or install globally
npm install -g systemlens
systemlens

That's it. One command.

📋 Commands

| Command | Description | |---------|-------------| | systemlens | Start real-time CLI monitoring | | systemlens --once | Single analysis snapshot | | systemlens --web | Launch beautiful web dashboard | | systemlens --web --port 4000 | Web dashboard on custom port | | systemlens --help | Show all options | | systemlens --version | Print version |

✨ Features

🧠 Intelligent Explanations — Not just "CPU is 85%", but "Chrome is consuming high CPU due to multiple open tabs"
🔗 Cause & Effect Chains — Links symptoms to causes with clear reasoning
🛠️ Developer Mode — Detects dev servers, hot-reload, and possible infinite loops
📈 Pattern Detection — Identifies sustained high usage, spikes, and trends over time
✅ Actionable Suggestions — Prioritized actions with impact ratings
🤖 Optional AI Enhancement — GPT-powered deeper insights (set OPENAI_API_KEY)
🌐 Web Dashboard — Real-time glassmorphic dark-mode UI
⚡ CLI Mode — Terminal-based monitoring with colored output and progress bars

🖥️ CLI Output

  ╔═══════════════════════════════════════════════════════════╗
  ║          🔬  S Y S T E M L E N S                         ║
  ║          CreatedBYNJ5.0                                   ║
  ╚═══════════════════════════════════════════════════════════╝

   🟡  SYSTEM STATUS: LIGHTLY LOADED  

  📊 System Summary
  CPU    ████░░░░░░░░░░░░░░░░  15%
  Memory ███████████████░░░░░  62%

  💬 What's Happening
  Your system is moderately loaded...

  🔗 Cause & Effect
  🌐 Cause: Browser with ~4 open tabs using significant resources
     Effect: Using 22% memory and 1% CPU

  ✅ Suggested Actions
  🌐 1. Close unused browser tabs and disable heavy extensions

🌐 Web Dashboard

systemlens --web
# Open http://localhost:3777

A premium dark-mode real-time dashboard with:

• Live metric cards with sparkline charts
• Natural language explanation panel
• Cause & Effect visualization
• Process table with categories
• Developer insights panel
• Prioritized suggestions

🤖 AI Enhancement (Optional)

# Set your OpenAI API key
export OPENAI_API_KEY=sk-your-key-here

# Run with AI insights
systemlens

AI adds:

• Deeper contextual insights
• Performance predictions
• Power-user tips

🏗️ Architecture

Collection → Classification → Analysis → Explanation → Suggestion → Rendering

| Layer | Purpose | |-------|---------| | 4 Collectors | CPU, Memory, Disk, Process data | | Classifier | Categorizes processes (Browser/Dev/System/Media) | | 4 Analyzers | Detects issues, spikes, core imbalance, swap pressure | | Explanation Engine | Converts analysis → human-language narratives | | Suggestion Engine | Prioritized, actionable recommendations | | Spike Detector | Time-series pattern detection | | AI Engine | Optional GPT-powered enhancement |

🔧 Configuration

All thresholds are configurable in src/utils/constants.js:

| Threshold | Default | Description | |-----------|---------|-------------| | CPU_HIGH | 80% | Triggers critical alert | | MEMORY_HIGH | 80% | Triggers critical alert | | SPIKE_THRESHOLD | 20% | Jump size for spike detection | | MONITORING_INTERVAL | 3000ms | Data refresh rate |

🖥️ Platform Support

| Platform | Status | |----------|--------| | Linux | ✅ Fully supported | | macOS | ✅ Fully supported | | Windows | ✅ Fully supported |

Requires Node.js 18+ — uses ES modules and top-level await.

📄 License

MIT — CreatedBYNJ5.0