xnos

xnos is a C++17 hardware monitor built from a platform-neutral core and native operating-system backends. The core defines an IMonitor interface (CPU, memory and GPU are required; disk, network and battery are optional and default to “unavailable”) and a set of plain metric structs. A MonitorFactory picks the backend at compile time (Linux, Windows or macOS), and a MetricCollector asks that backend for a full SystemMetrics snapshot on every cycle.

On Linux the backend reads the kernel’s own files directly: CPU utilisation is computed from the difference between two /proc/stat readings (idle plus iowait against total time, with a short 250 ms priming sample on the first call), load averages come from /proc/loadavg, and memory comes from /proc/meminfo (used = MemTotal minus MemAvailable). GPU data is read from the DRM sysfs nodes (gpu_busy_percent, mem_info_vram_used, mem_info_vram_total) and falls back to nvidia-smi when no such node exists; battery state is read from /sys/class/power_supply. On Windows the backend uses GetSystemTimes for CPU, GlobalMemoryStatusEx for memory, DXGI for the GPU name and dedicated VRAM size, and GetSystemPowerStatus for the battery. The macOS backend is currently a buildable stub that reports every metric as unavailable.

Each snapshot is passed to a terminal renderer in one of four modes: a boxed dashboard that clears and redraws the screen with ANSI escape codes under a timestamped header, a one-line compact view, a detailed view that adds disk, network and battery lines, or a single-line JSON object for scripts. Any metric that a platform cannot supply is stored internally as a negative value and shown as N/A in terminal output and null in JSON output. After rendering, the snapshot can be appended as a JSON line to a log file, and CPU and memory usage are checked against thresholds (defaults 90% and 85%); a breach prints an alert: line to stderr. The loop repeats at a configurable refresh interval until it is interrupted, a fixed duration elapses, or a single --test-mode collection completes.

Features

• Cross-platform IMonitor interface with Linux, Windows, and macOS backends (macOS is currently a stub that reports all metrics as N/A)
• CPU utilisation, plus 1, 5 and 15 minute load averages on Linux
• Memory utilisation with total, used, and free in MiB
• GPU name, engine utilisation, and VRAM used/total
  • Linux: DRM sysfs, with an nvidia-smi fallback
  • Windows: name and dedicated VRAM total via DXGI (engine utilisation and VRAM used are N/A)
• Battery percentage and status on Linux and Windows
• Disk and network throughput fields exist in the metric types, the detailed view and the JSON output, but no backend fills them yet, so they currently show N/A / null
• Dashboard, compact, detailed, and JSON terminal modes
• N/A in terminal output and null in JSON output for unavailable metrics
• INI-style configuration file (refresh_rate_ms, color_enabled, cpu_threshold, memory_threshold are read)
• Threshold alerts for CPU and memory, printed to stderr, with --threshold-cpu and --threshold-mem command-line overrides
• Optional JSON-lines logging (--log)
• Fixed-duration runs (--duration) and one-shot collection (--test-mode)
• Shortcut flags --compact and --json
• Native OS APIs only; the one optional external tool is nvidia-smi, used as a GPU fallback on Linux
• CMake build with warnings enabled by default (ENABLE_WARNINGS, optional WARNINGS_AS_ERRORS), plus unit and end-to-end tests
• Multi-stage Dockerfile; GitHub Actions workflows for CI (Linux, Windows, macOS), CodeQL, tagged releases, and multi-arch (amd64/arm64) Docker image publishing to GHCR

Build

cmake -B build -DBUILD_TESTS=ON
cmake --build build --parallel
ctest --test-dir build --output-on-failure

On Windows with a multi-config generator, add --config Release or --config Debug to the build and test commands.

The executable is built as iso-kernos (the project name in CMake). The Docker image installs it as xnos.

Run

./build/iso-kernos --mode dashboard
./build/iso-kernos --compact
./build/iso-kernos --json --duration 5
./build/iso-kernos --test-mode --mode compact

Options

Usage: iso-kernos [OPTIONS]

  -h, --help              Show help
  -v, --version           Show version
  -r, --refresh <ms>      Refresh rate in milliseconds (default 1000)
  -m, --mode <mode>       dashboard|compact|detailed|json
  -c, --config <file>     Read an INI-style config file
  -l, --log <file>        Append JSON metrics to a log file
      --duration <sec>    Stop after a fixed duration
      --test-mode         Collect once and exit
      --no-color          Disable ANSI color output
      --compact           Shortcut for --mode compact
      --json              Shortcut for --mode json
      --threshold-cpu <%> CPU alert threshold (default 90)
      --threshold-mem <%> Memory alert threshold (default 85)

Structure

src/
├── core/       Interfaces, metric types, config, factory, collector
├── platform/   Linux, Windows, and macOS native monitor implementations
├── display/    Terminal renderers and formatters
├── alerts/     Threshold evaluation and JSON logging
└── utils/      Small shared utilities

tests/          Unit and integration tests
docs/           Architecture, API, platform notes, contributing guide

See docs/ARCHITECTURE.md and docs/API.md for details.

This site is open source. Improve this page.