Overview

Guro is a sophisticated terminal-based diagnostic toolkit designed for granular system resource monitoring and hardware analysis. Built for engineers and enthusiasts, it provides a desktop-class dashboard experience within the command-line environment, delivering telemetry across Linux, macOS, and Windows, with explicit availability reporting for unsupported sensors.

🌐 Website: guro.pages.dev

Visual Presentation

1. Performance Telemetry View

High-concurrency monitoring of CPU cores, memory allocation, and active process telemetry

2. Hardware Thermal Schematic

Spatial temperature mapping across integrated hardware components with synchronized trend analysis.

Key Capabilities

Intelligent Monitoring

The performance module utilizes high-frequency sampling to provide real-time ASCII-based historic trending. It shows aggregate CPU utilization, memory usage, GPU metrics where supported, and the ten processes using the most CPU.

Thermal Intelligence

Guro reads Linux hwmon sensors through psutil, OpenHardwareMonitor WMI sensors on Windows, and available powermetrics readings on macOS. NVIDIA temperatures can also come from nvidia-smi. Missing readings display as N/A. The heatmap is a component schematic; its cells do not represent independently measured spatial temperatures. Optional estimates require --estimates and are labeled.

Hardware-Agnostic Benchmarking

CPU benchmarks report NumPy/BLAS matrix throughput; memory benchmarks report copy bandwidth using reusable buffers capped at 32 MiB and 1% of available memory. Runs stop at 90% system memory use or a measured component temperature of 90°C. Thermal coverage depends on exposed sensors and is included in the report. GPU workloads are currently unsupported; guro gpu provides device telemetry.

Network Intelligence

Real-time bandwidth monitoring with per-interface upload/download sparklines, TCP state distribution (ESTABLISHED, LISTEN, TIME_WAIT, etc.), process-level connection tracking, and /proc/net/snmp protocol statistics — all with zero additional dependencies beyond psutil.

Installation

Current release: 1.1.7. See the detailed release notes.

Requires Python 3.9 or newer.

Standard Method

pip install guro

Isolated Environment (Recommended)

pipx install guro

Operational Interface

Access Guro via its unified command-line interface.

Structured output and exports

guro doctor --format json
guro monitor --duration 10 --format jsonl --output samples.jsonl
guro heatmap --duration 10 --format json --output temperatures.json
guro network --duration 10 --export --output bandwidth.csv
guro gpu --format json
guro benchmark --type mini --cpu-only --format json --output benchmark.json

--format json writes a JSON array for monitoring sessions and a single JSON value for snapshots and benchmark reports. jsonl writes one JSON value per line. Structured output contains no banners or status spinners. --output writes to a file; otherwise structured output goes to stdout. Errors go to stderr and return a nonzero exit status. Existing destination files are replaced.

CSV (--export) and structured monitoring exports stream and flush each sample. Recent dashboard history is bounded to 60 samples. JSON arrays close on normal completion, Ctrl+C, and handled collection errors; use JSONL for recovery after abrupt process termination. Network speed pairs are [upload_bytes_per_second, download_bytes_per_second]. Connection permissions are reported separately from an empty connection list. Network totals may include virtual and loopback interfaces.

Temperature objects include value (null when unavailable), unit, source, timestamp, and available. --estimates affects only missing heatmap readings; measured readings always take precedence. Estimates are excluded from benchmark safety decisions.

mini and god request total budgets of 30 and 60 seconds. Default runs split time between CPU and memory workloads; --cpu-only uses the full budget for CPU. Collection and individual operations can overrun a deadline. Reports include actual elapsed time, configuration, and an explicit completion/abort outcome. GPU-only requests return unsupported with a nonzero status. Throughput excludes telemetry time; results depend on the NumPy/BLAS build, thread settings, cache behavior, and background load. Memory copy MB/s counts payload bytes copied, not combined read/write bus traffic.

Roadmap

🚀 Coming soon — PRs, ideas, and discussions are warmly welcomed!

Have a feature in mind? Open an issue or start a discussion — every idea counts.

💖 Why Funding Matters

Testing system-level tooling demands real hardware — high-end GPUs, multi-CPU servers, and diverse cloud VMs for cross-platform validation. Your support helps rent these environments so Guro can be tested thoroughly across Linux, macOS, and Windows.

Community and Development

Guro is an open-source project that adheres to professional development standards.

• Website: guro.pages.dev
• Developer Guide: Comprehensive guidelines can be found in CONTRIBUTING.md.
• Architecture: In-depth module analysis is available in the project documentation.
• License: Released under the MIT License.
• Support: GitHub Sponsors · Buy Me A Coffee

Star History