Here's a polished, Ravenclaw-consistent README for sys-health v1.0 — keeping the same structure, energy, and scannability as the rest of your toolchain (heartbeat-hub, node-watch, etc.):
# sys-health 🏥 v1.0
**Autonomous Linux system health scanner**
Runs essential checks (CPU load/temp, memory/swap, disk usage, UFW status, pending apt updates, etc.), outputs structured JSON, saves timestamped reports, and offers pretty reports + safe auto-fixes.
Your machine's personal medic — catching issues before they crash the agent swarm.
## 🚀 Quickstart
```bash
cd ~/tools/projects/sys-health
npm install
npm link # → ~/bin/sys-health
# Full scan → JSON report saved
sys-health scan
# View latest pretty report + recs
sys-health report
# Apply safe auto-fixes (apt update/upgrade, ufw enable if off, etc.)
sys-health fix --auto
# Use --dry first to preview!
Reports saved to: ~/tools/projects/sys-health/reports/YYYY-MM-DD/
(with latest.json symlink for easy access)
📋 Commands
| Command | Description |
|---|---|
sys-health scan |
Run all checks → output JSON to stdout + save to reports/ |
sys-health report |
Pretty-print latest report + color-coded status + recommendations |
sys-health fix --auto |
Auto-apply safe, non-destructive fixes (confirmation prompt by default) |
sys-health fix --dry |
Preview fixes without applying (recommended for first runs) |
sys-health list-checks |
Show available check modules (expandable) |
Note: Some actions (e.g. apt upgrade, ufw enable) require elevated privileges. Configure passwordless sudo for the user or run manually with sudo.
✨ Features
- Hacker-robust: Graceful error handling, async/parallel checks where possible
- Structured output: Clean JSON reports (easy for heartbeat-hub or scripts)
- Timestamped + latest symlink — historical tracking
- Recommendations engine: Actionable advice (e.g., "High load → check top processes")
- Modular checks: Easy to add new ones (CPU, Mem, Disk, Network, Services, etc.)
- Safe fixes mode: Only low-risk actions by default
Example report snippet (colorized in terminal):
🩺 Sys-Health Report — 2026-02-08 02:45 AM EST
├── CPU Load ⚠️ 4.2 / 8 cores (high – possible agent overload)
├── Memory ✅ 12.4GB / 32GB used (38%)
├── Swap ✅ 0% used
├── Disk (/home) 🟡 82% used (418GB free – cleanup suggested)
├── UFW ✅ Active & enabled
├── Apt Updates ⚠️ 7 packages upgradable (security patches available)
└── Overall Status 🟡 Warning – minor maintenance needed
Recommendations:
→ Run `apt upgrade` to apply security updates
→ Investigate high CPU (top/htop or ps aux)
→ Consider running backup-md cleanup on large logs
🧪 Tests
npm test # Mock checks + JSON schema validation (stub/expanding)
🔧 Built With
- yargs — flexible CLI parsing
- fs-extra — safe file/report handling
- child_process / execa — robust command execution
- chalk — terminal colors & formatting
- systeminformation or native
os/fs— lightweight system probes
🚀 Roadmap
| Version | Status | Key Features |
|---|---|---|
| v1.0 | ✅ Live | Core checks (CPU/Mem/Disk/UFW/Apt), JSON reports, basic fixes |
| v1.1 | Planned | More checks (temp, processes, services), thresholds/alerts |
| v1.2 | Idea | Integration with heartbeat-hub, email/Slack notify on critical |
| v2.0 | Future | Predictive analysis, auto-remediation scripts, web UI hook |
sys-health v1.0 is live — keeping the hardware breathing.
Diagnose fast, fix faster. 🏥🦅
Grind on.
Last updated: 2026-02-08
### Compact / quick-scan version (for notes or dashboard)
```markdown
# sys-health 🏥 v1.0
System vitals CLI
```bash
sys-health scan # → JSON + save
sys-health report # pretty + recs
sys-health fix --auto # safe fixes
Checks: CPU • Mem • Disk • UFW • Apt
Reports → reports/latest.json
Roadmap
v1.0 ✓ core scan/report/fix
v1.1 → more probes + alerts
v1.2 → notify integration
v2 → predictive + UI
Live & diagnosing since 2026-02-08 🏥
This one pairs naturally with heartbeat-hub (higher-level agent checks) and node-watch (real-time polling).
Want:
- mocked full JSON report example?
- sudo config snippet for seamless use?
- more cyber-raven flair?
Or ready for the next tool (tts-queue? web-scout? log-tail?) — let's keep building the swarm! 🦅