disk-guardian

S.M.A.R.T. drive health scanner for macOS and Linux.

Scripts

All scripts are in scripts/. Run them in sequence or pipe them together:

CODEBLOCK0

Data is stored in ~/.openclaw/workspace/disk-guardian/ by default. Use --data-dir to override on any script.

Workflow

1. 1. Run scan_drives.py — detects drives and runs smartctl -a on each. Outputs JSON.
2. Pipe to parse_smart.py — extracts health attributes, assesses status (Good/Warning/Critical).
3. Pipe to report.py — generates markdown report with risk rankings and recommendations.
4. Optionally pipe to history.py --record to log the scan and get trend alerts.

Prerequisites

smartctl must be installed:

• - macOS: INLINECODE8
• Linux: sudo apt install smartmontools or INLINECODE10

If smartctl is missing, scan_drives.py will output the install command and exit gracefully.

Script Details

scan_drives.py

• - macOS: uses diskutil list to find whole disks, then INLINECODE13
• Linux: uses lsblk to find block devices, then INLINECODE15
• INLINECODE16: prepend sudo to smartctl commands (needed on Linux without udev rules)
• Outputs JSON: INLINECODE17

parse_smart.py

• - Detects drive type: NVMe, SSD, or HDD
• SATA/SSD: parses attribute table, extracts Reallocated Sector Count, Current Pending Sector, Uncorrectable Errors, Temperature, Power-On Hours, Read Error Rate, Seek Error Rate, and more
• NVMe: parses health log for Available Spare, Percentage Used, Media Errors, Unsafe Shutdowns, Critical Warning
• Assigns health_status: Good / Warning / Critical
• INLINECODE18: read from file instead of stdin
• INLINECODE19: parse a single raw smartctl text dump

history.py

• - --record: append current scan to INLINECODE21
• INLINECODE22: analyze stored history for concerning patterns (rising reallocated sectors, climbing temps, declining NVMe spare)
• INLINECODE23: show last N entries per device
• INLINECODE24: use alternate storage location
• INLINECODE25: filter output to one device

report.py

• - Generates markdown with drive inventory table, per-drive status, risk ranking with scores, human-readable flag explanations, trend alerts, and recommendations
• Risk ranking accounts for health status, flag severity, trend alerts, and drive age (power-on hours)
• INLINECODE26: save report to file instead of printing
• INLINECODE27: load pre-computed trend JSON

SMART Attribute Reference

See references/smart-attributes.md for plain-English explanations of the 10 most critical SMART attributes and NVMe health indicators. Read it when explaining specific attributes to the user or when triaging a flagged drive.

Edge Cases

• - smartctl not installed: scan_drives.py prints install instructions and exits with code 2
• Permission denied: Output includes hint to use --sudo; on Linux, add user to disk group as permanent fix
• Virtual drives (VMware, loop devices): smartctl will return errors; these are captured and included in error entries
• NVMe vs SATA: drive type auto-detected; NVMe uses health log fields instead of attribute table
• Corrupt history: history.py backs up the file and starts fresh automatically