SysWatch Terminal Diagnostics

Skill by ara.so — Daily 2026 Skills collection.

SysWatch is a single-host system diagnostics TUI written in Rust for macOS and Linux. It consolidates what you'd normally get from htop, iostat, vm_stat, powermetrics, launchctl, and many other tools into twelve navigable tabs, with plain-English anomaly detection and a session-wide scrubber.

Install

git clone https://github.com/matthart1983/syswatch.git && cd syswatch
cargo build --release
./target/release/syswatch

Requirements: Rust 1.75+. No extra system dependencies on Linux. macOS links against system frameworks automatically.

Crates.io, Homebrew, and pre-built binaries are planned for the v0.1 release.

Running SysWatch

# Default — 1 Hz refresh
./target/release/syswatch

# 2 Hz refresh (500 ms tick)
syswatch --tick 500

# Boot directly into a specific tab
syswatch --tab procs
syswatch --tab cpu
syswatch --tab insights

Key Bindings

1 2 3 4 5 6 7 8 9   Overview / CPU / Mem / Disks / FS / Procs / GPU / Power / Services
0 - +               Net / Timeline / Insights
Tab / Shift-Tab     Cycle tabs forward / backward
↑ / ↓               Select row (Procs, Services tabs)
s                   Cycle sort column (Procs, Services tabs)
← / →               Scrub session backward / forward (Timeline tab)
Home / End          Jump to oldest sample / return to live
p                   Pause collection
q / Ctrl-C          Quit

Tabs Reference

Key	Tab	Data Source / Replaces
`1`	Overview	Dashboard of all subsystems
`2`	CPU	`htop` CPU panel, `mpstat`, `top -d`
`3`	Memory	`free`, `vm_stat`, `htop` mem panel
`4`	Disks	`iostat`, `iotop` (aggregate)
`5`	Filesystems	`df -h`, `df -i`, `mount`
`6`	Procs	`htop`, `ps auxf`, `pstree`
`7`	GPU	`ioreg AGXAccelerator` / `/sys/class/drm`
`8`	Power	`pmset`, `ioreg AppleSmartBattery` / `/sys/class/power_supply`
`9`	Services	`launchctl list` / `systemctl list-units`
`0`	Net	`nettop`, `iftop`
`-`	Timeline	Session log + scrubber
`+`	Insights	Plain-English anomaly cards

Architecture Overview

src/
├── main.rs              CLI entry point + arg parsing
├── app.rs               Event loop, tab state, scrub plumbing
├── collect/
│   ├── collector.rs     sysinfo-backed CPU/Mem/Procs + dispatch
│   ├── gpu.rs           system_profiler / sysfs DRM
│   ├── power.rs         ioreg / pmset / sysfs power_supply
│   ├── services.rs      launchctl / systemctl
│   └── ring.rs          Bounded history ring + nth_back for scrubbing
├── insights/            Pure functions over (History, &Snapshot)
├── tabs/                One file per tab — thin renderers over the model
└── ui/
    ├── chrome.rs        Header, tab bar, footer
    ├── palette.rs       Single color source of truth
    └── widgets.rs       block_bar, sparkline, panel helpers

Refresh model:

1 Hz fast loop: CPU, Memory, Procs, Net, IO
5 s slow loop: Power, Services (subprocess-heavy on macOS)
CPU budget target: < 0.5% at idle

Extending SysWatch: Adding a Collector

Collectors live in src/collect/. Each one populates a typed Snapshot struct and is called from collector.rs.

// src/collect/my_subsystem.rs

use crate::collect::ring::Ring;

#[derive(Debug, Clone)]
pub struct MySnapshot {
    pub value: f64,
    pub label: String,
}

pub struct MyCollector {
    history: Ring<MySnapshot>,
}

impl MyCollector {
    pub fn new(capacity: usize) -> Self {
        Self {
            history: Ring::new(capacity),
        }
    }

    pub fn collect(&mut self) -> MySnapshot {
        // Replace with real data collection
        let snap = MySnapshot {
            value: 42.0,
            label: "example".to_string(),
        };
        self.history.push(snap.clone());
        snap
    }

    /// Returns the nth most recent snapshot (for scrubbing).
    pub fn nth_back(&self, n: usize) -> Option<&MySnapshot> {
        self.history.nth_back(n)
    }
}

Extending SysWatch: Adding a Tab Renderer

Tab renderers live in src/tabs/. They receive the current (or scrubbed) snapshot and render into a ratatui Frame.

// src/tabs/my_tab.rs
use ratatui::{
    layout::{Constraint, Direction, Layout, Rect},
    style::{Color, Style},
    widgets::{Block, Borders, Paragraph},
    Frame,
};
use crate::collect::my_subsystem::MySnapshot;

pub fn render(f: &mut Frame, area: Rect, snap: &MySnapshot) {
    let block = Block::default()
        .title(" My Tab ")
        .borders(Borders::ALL)
        .border_style(Style::default().fg(Color::Cyan));

    let text = Paragraph::new(format!(
        "Value: {:.2}\nLabel: {}",
        snap.value, snap.label
    ))
    .block(block);

    f.render_widget(text, area);
}

Wire it into app.rs's tab dispatch match arm and add the tab label to ui/chrome.rs.

Extending SysWatch: Adding an Insight

Insights are pure functions in src/insights/. They take history + the latest snapshot and return zero or more anomaly cards.

// src/insights/my_insight.rs
use crate::collect::my_subsystem::MySnapshot;

#[derive(Debug, Clone)]
pub struct InsightCard {
    pub title: String,
    pub body: String,
    pub suggested_tab: &'static str,
}

pub fn check(snap: &MySnapshot) -> Vec<InsightCard> {
    let mut cards = vec![];

    if snap.value > 90.0 {
        cards.push(InsightCard {
            title: "High value detected".to_string(),
            body: format!(
                "Current value is {:.1}, which exceeds the 90.0 threshold.",
                snap.value
            ),
            suggested_tab: "my_tab",
        });
    }

    cards
}

Using the Ring Buffer (Session Scrubbing)

The Ring<T> type in src/collect/ring.rs is the backbone of session scrubbing. Any collector that wraps its history in a Ring gets scrubbing for free when the tab renderer calls nth_back.

use crate::collect::ring::Ring;

// Create a ring holding 3600 samples (1 hour at 1 Hz)
let mut ring: Ring<f64> = Ring::new(3600);

// Push a new sample each tick
ring.push(42.0);

// In scrub mode, app.rs tracks `scrub_offset: usize`
// 0 = live, N = N ticks in the past
let scrub_offset = 5; // 5 seconds ago
if let Some(val) = ring.nth_back(scrub_offset) {
    println!("Value 5s ago: {}", val);
}

In app.rs, the ←/→ keys increment/decrement scrub_offset, and every tab renderer receives the offset so they all show the same point in time.

Optional Cargo Features

# Cargo.toml — enable NVIDIA GPU stats (requires NVML / nvidia-smi)
[features]
gpu-nvidia = ["nvml-wrapper"]

# Enable SMART disk health (requires smartctl in PATH)
smart = []

Build with a feature:

cargo build --release --features gpu-nvidia
cargo build --release --features smart
cargo build --release --features gpu-nvidia,smart

Platform Notes

macOS

GPU utilization and used memory on Apple Silicon: available without sudo via ioreg AGXAccelerator PerformanceStatistics.
Fan speeds, per-component power, GPU temperature: require sudo powermetrics. SysWatch shows available data and displays a one-line note where sudo is needed — it never prompts.
Thermal zone temps require IOReport private FFI (deferred).

Linux

Thermal zones: available for free via sysfs (/sys/class/thermal/).
GPU data: read from /sys/class/drm.
Power supply: /sys/class/power_supply.
No elevated privileges required for core functionality.

Common Patterns

Checking live vs. scrubbed state in a tab

// In app.rs, scrub_offset == 0 means "live"
pub struct App {
    pub scrub_offset: usize,
    // ...
}

// In a tab renderer:
pub fn render(f: &mut Frame, area: Rect, app: &App) {
    let snap = if app.scrub_offset == 0 {
        app.collector.latest()
    } else {
        app.collector.nth_back(app.scrub_offset)
            .unwrap_or_else(|| app.collector.latest())
    };
    // render snap...
}

Pausing collection

The p key sets app.paused = true. The event loop skips collect() calls but the UI still redraws on keypress, so scrubbing works while paused.

if !app.paused {
    app.collector.collect();
}

Troubleshooting

Symptom	Fix
`cargo build` fails on macOS with framework linker errors	Ensure Xcode Command Line Tools are installed: `xcode-select --install`
GPU tab shows "no data" on Apple Silicon	Normal without sudo for temp/power; util + memory should appear via ioreg
Services tab is slow to update	Expected — launchctl/systemctl are subprocess-heavy; they run on the 5 s slow loop
Timeline scrubbing shows stale data	The ring capacity is set at startup; scrubbing is limited to collected history
Net tab shows no interfaces	May need to run as a user with access to network stats; check `netwatch-sdk` compatibility
`syswatch --tab X` not recognized	Use lowercase tab names: `cpu`, `mem`, `disks`, `fs`, `procs`, `gpu`, `power`, `services`, `net`, `timeline`, `insights`, `overview`

Anti-Goals (What SysWatch Will Not Do)

Not multi-host — use NetWatch's web dashboard for fleet monitoring.
Not a daemon — no background collector, no Prometheus push.
Not interactive — read-only by design; does not kill, renice, unmount, or restart anything.
Not a log search UI — surfaces OOM kills as signals; does not index logs.
No smooth charts — block sparklines and real numbers only.

Related Projects

NetWatch — sibling network diagnostics TUI, same chrome and palette.
netwatch-sdk — shared parsers for net interface counters and aggregate disk IO used by both tools.

syswatch-terminal-diagnostics