HardwareLens 1.0.0 Hardware Health Hub - Simple variant ================================================================== HardwareLens is a DESKTOP COMMAND-LINE TOOL for Windows and macOS (a Linux build is also provided). It is not a web app. An earlier browser version of this concept existed and has been deleted; nothing in this program runs in a browser or talks to a network. HardwareLens answers one question in one command: "What is this computer, and does anything about it look wrong?" It prints a single readable page - a SYSTEM REPORT CARD - in plain English, for someone who is not a system administrator. Run it, read it, or save it with --out and send the file to whoever is helping you. ------------------------------------------------------------------ HOW IT DIFFERS FROM ITS SIBLINGS ------------------------------------------------------------------ DevicePulse keeps a HISTORY. Its axis is time: it appends snapshots of one machine to a log and warns when usage grows. PCHealth is the FLEET view. Its axis is many machines: it compares workstations to each other and flags statistical outliers. CorePilot, ThermalFlow, SystemPulse are BENCHMARKS. Their output is scores meant to be compared against other scores. HardwareLens is the ONE-PAGE REPORT CARD for the machine in front of you, right now. No history is kept, no other machine is involved, and the speed check exists only to produce one plain-English sentence inside the report. Its output is meant to be READ and HANDED TO SOMEONE, not graphed or compared. ------------------------------------------------------------------ COMMANDS ------------------------------------------------------------------ hardwarelens report [--watch ...] [--out ] [--json] The report card. Five sections: WHAT THIS COMPUTER IS hostname, operating system, processor family, logical CPU count, GOMAXPROCS, Go runtime version and compiler. SPEED CHECK a short (roughly 400 ms total) CPU measurement, stated as millions of operations per second on one core and on all cores, the all-core speedup, and a plain-English rating. MEMORY USED BY THIS TOOL runtime.MemStats figures for the hardwarelens process itself, human-readable. Explicitly labelled as this program's own memory, NOT the machine's RAM. WHAT IS IN THE FOLDERS YOU ASKED ABOUT for each --watch path: total bytes, file count, folder count, average file size, and the largest single file with its share of the total. WHAT THIS LOOKS LIKE the diagnostic section - plain-English remarks, each one derived from a number printed elsewhere in the same report, each printed with the measurement it came from on an "evidence:" line. --out writes the same bytes that were printed to the named file. It is the ONLY file HardwareLens ever writes. hardwarelens inventory [--json] The static facts only. No benchmark, so it returns instantly (milliseconds) and contains no timing-derived number at all. hardwarelens bench [--seconds N] [--json] The speed check on its own. hardwarelens help | -h | --help usage, exit 0 hardwarelens version version string Flags may be written before or after positional arguments. A bad invocation prints the reason plus the usage text to stderr and exits 1. ------------------------------------------------------------------ WHAT IS ACTUALLY IMPLEMENTED ------------------------------------------------------------------ Everything below is real, working code in this binary. Nothing is simulated, stubbed or hard-coded. * Hostname, from os.Hostname(). * Operating system and processor FAMILY, from runtime.GOOS and runtime.GOARCH. "64-bit Intel/AMD (x86-64)" is a translation of the string "amd64" - it is an instruction-set family, not a CPU model. * Logical CPU count, from runtime.NumCPU(). * GOMAXPROCS, from runtime.GOMAXPROCS(0) - the number of those CPUs this program may actually use. * Go runtime version and compiler, from runtime.Version() and runtime.Compiler. * Process memory, from runtime.ReadMemStats: bytes in use, bytes reserved from the OS, total ever allocated, heap in use and held, live object count, completed GC cycles, live goroutines. * Recursive directory measurement, from filepath.WalkDir: total bytes, regular-file count, sub-directory count, mean file size, largest file and its percentage of the total, and a count of entries that could not be read. Symlinks and other non-regular entries are counted as neither files nor bytes. * A real CPU benchmark (described below). * Diagnostic observations derived from those measurements. * JSON output for all three commands. ------------------------------------------------------------------ THE SPEED CHECK - WHAT IT ACTUALLY DOES ------------------------------------------------------------------ The unit of work is a ROUND. One round: 1. fills a 64 KiB buffer (8192 uint64 words) with a splitmix64-style 64-bit avalanche sequence seeded from the round number, then 2. makes 32 further mixing passes over that buffer, then 3. returns a checksum. That is 8192 * (1 + 32) = 270,336 mix operations per round. A round is a pure function of its round number: the buffer is fully overwritten on entry, so no round depends on what ran before it, and per-round checksums are XOR-folded, so the result does not depend on how rounds are shared between workers or on the order workers finish. The default (fixed) workload is: single-core phase 700 rounds on 1 goroutine 189,235,200 ops all-core phase 1,400 rounds on GOMAXPROCS 378,470,400 ops Both counts are compile-time constants. THE WORK IS THEREFORE IDENTICAL ON EVERY RUN: the operation counts and the two checksums are byte-for-byte the same each time, and only the elapsed TIME varies. That is what makes it a measurement rather than a printed constant - and if the machine is busy, the same work takes longer and the score falls. --seconds N switches to the timed variant: the round SIZE stays constant and rounds are executed until an N/2-second budget expires in each phase, so the round count varies instead. The reported ops count is always rounds * 270,336 - the true number of operations performed. It measures 64-bit integer throughput and cache behaviour of this machine as it is running right now. It is NOT a graphics, disk or memory-bandwidth test, it is not a thermal or sustained-load test, and its numbers are not comparable with any other benchmark's numbers. It is used for exactly one thing: to produce the plain-English rating sentence in the report card. The rating bands, applied to the measured single-core figure, are: < 100 million ops/sec very slow < 250 slow < 500 ordinary < 900 fast otherwise very fast These bands are a documented rule of thumb applied to a number this run actually measured. The report prints the band boundaries alongside the rating so you can see exactly how the wording was chosen. ------------------------------------------------------------------ THE DIAGNOSTIC SECTION - HOW REMARKS ARE DERIVED ------------------------------------------------------------------ No remark is canned. Each is emitted only when its trigger condition holds against a measured value, and each prints the numbers it was derived from. cpu-count-low NumCPU <= 2 cpu-count-ok NumCPU in 3..7 cpu-count-high NumCPU >= 8 gomaxprocs-capped GOMAXPROCS < NumCPU cpu-speed always, quoting the measured single-core figure and the band it fell into parallel-ok all-core speedup >= GOMAXPROCS/2 parallel-poor all-core speedup < GOMAXPROCS/2 path-empty a watched path contains 0 regular files path-dominated the largest file is >= 50% of that path's total bytes and the path holds more than one file path-many-small >= 1000 files with a mean file size under 4 KiB path-unreadable one or more entries could not be read during the walk nothing-notable emitted only if no other condition fired Every threshold above is a comparison against a number that also appears in the printed report, so any remark can be checked by hand. ------------------------------------------------------------------ WHAT IS *NOT* IMPLEMENTED, AND WHY ------------------------------------------------------------------ READ THIS PART. HardwareLens deliberately OMITS the following. It does not estimate them, infer them, or print a plausible-looking placeholder. If you want a tool that tells you your CPU model, this is not that tool yet. * CPU MODEL NAME, VENDOR AND CLOCK SPEED - not reported. * PHYSICAL CORE COUNT (as distinct from logical CPUs) - not reported. * TOTAL AND FREE SYSTEM RAM - not reported. The memory section is this program's own usage and says so. * GPU MAKE, MODEL AND VIDEO MEMORY - not reported. * CPU / GPU / DRIVE TEMPERATURES - not reported. * FAN SPEEDS - not reported. * DRIVE SMART HEALTH, WEAR LEVEL AND ERROR COUNTERS - not reported. * BATTERY HEALTH AND CYCLE COUNT - not reported. * FREE SPACE on the filesystem holding a watched path - not reported. The folder section reports what is IN the folder, not what is left on the disk. * WHOLE-MACHINE CPU LOAD - not reported. The speed check measures this program's own throughput, which a busy machine does drag down, but that is a symptom, not a load figure. The reason is the same in every case: the Go standard library cannot read them portably. Each one requires native, per-operating-system code - CPU model / cores CPUID on x86, sysctl on macOS, WMI or the registry on Windows RAM total / free sysinfo(2), sysctl hw.memsize, GlobalMemoryStatusEx GPU vendor SDKs, IOKit, DXGI / WMI temperatures, fans sensor APIs, SMC on macOS, a kernel driver or WMI provider on Windows SMART raw ATA/NVMe pass-through ioctls, usually requiring administrator rights battery IOKit power sources, GetSystemPowerStatus free disk space statfs(2), GetDiskFreeSpaceExW machine CPU load /proc/stat, host_statistics, PDH counters That list IS the roadmap: adding them means adding per-OS implementations with cgo or syscall bindings, plus a build matrix per platform. Until that work is done, HardwareLens omits the fields. The report ends with a "WHAT THIS TOOL CANNOT SEE" section that names every one of them, so a reader is never left assuming a missing measurement was a clean bill of health. This is the whole design principle: an honest short report beats a convincing long one. ------------------------------------------------------------------ READ-ONLY BEHAVIOUR ------------------------------------------------------------------ HardwareLens opens directories to list them and stats files to size them. It never opens a watched file's contents, never renames, never deletes, never changes a timestamp or a permission. The single exception is the file named by "report --out", which is created or overwritten with 0644 permissions. There are no debug flags and no environment variables that change behaviour. No network connection is ever made. ------------------------------------------------------------------ BUILD ------------------------------------------------------------------ Go standard library only - no third-party dependencies at all, so an offline build works: GOPROXY=off go build -o hardwarelens . Shipped binaries in dist/ are built with -ldflags="-s -w": hardwarelens-windows-amd64.exe Windows, 64-bit Intel/AMD hardwarelens-darwin-arm64 macOS, Apple silicon hardwarelens-darwin-amd64 macOS, Intel hardwarelens-linux-amd64 Linux, 64-bit Intel/AMD ------------------------------------------------------------------ EXAMPLES ------------------------------------------------------------------ hardwarelens report hardwarelens report --watch ~/Documents --watch ~/Downloads hardwarelens report --watch "C:\Users\me\Downloads" --out report.txt hardwarelens report --json > report.json hardwarelens inventory hardwarelens bench --seconds 3