macOS_FSMetrics

TTU HackWesTex 2026 — Developer Challenge submission

Monitors file systems on macOS (local APFS and shared NFS/pNFS) — the kind of storage behind local AI setups where terabytes sit at rest with no admin-facing tooling built for macOS.

What it does

• Checks filesystem and drive health
• Measures I/O performance in GB/s
• Tracks capacity and per-user storage usage
• Watches local (APFS) and shared (NFS/pNFS) volumes
• Shows every analytic with charts/bars in the dashboard
• Alerts on full volumes, failing drives, and rapid per-user growth
• Surfaces NFS timeouts/retransmits, and stalled I/O

Dashboard Screenshots

Performance charts under load — throughput, IOPS, and average I/O size:

Animated walkthrough — dashboard, NFS volume, per-user quotas, and the alert workflow with View activity:

Build & run

Requires macOS 15+, Xcode and the Swift 6 toolchain from the Command Line Tools.

# With Xcode installed
xcode-select --install

The first build fetches dependencies, so it needs network access.

git clone https://github.com/TroyDixon/macOS_FSMetrics.git
cd macOS_FSMetrics

# Dependencies 
swift build

# Set starter config 
mkdir -p "$HOME/Library/Application Support/FSMetrics"
cp config.example.json "$HOME/Library/Application Support/FSMetrics/settings.json"

# Build Application
Scripts/bundle.sh
ditto build/FSMetrics.app /Applications/FSMetrics.app
xattr -dr com.apple.quarantine /Applications/FSMetrics.app 2>/dev/null || true
codesign --verify --verbose /Applications/FSMetrics.app

# Grant Permissions
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"
# Select "+" then "FSMetrics" Toggle **ON**

# Launch Application
open /Applications/FSMetrics.app

Using the app

The app lives in the menu bar (no Dock icon, no window at launch). See docs/OPERATING.md for the day-to-day rundown.

• Status — icon shows worst current severity and latest throughput
• Open Dashboard — throughput and capacity charts, volume cards, per-user usage, recent alerts
• Collect Now — runs a collection cycle immediately
• Settings… — volumes, scan intervals, thresholds, webhook URL, database path
• Quit — stops the app and background collection

Configuration

Look in the Settings tab of the icon in the Menu Bar

You can set capacity warn/critical levels, per-user growth limits, a per-volume per-user quota (0 disables), stall detection, and alert cooldowns.

Alerts

• Capacity warnings when a volume fills past configured levels
• Per-user growth warnings when someone writes a lot in a short window
• Per-user quota warnings when a user's total crosses a volume's configured limit (user_quota_bytes, 0 disables the rule)
• Drive and mount warnings (SMART failures, unexpected read-only volumes, NFS mounts down)
• Stall warnings when I/O samples stop arriving
• Duplicate alerts are suppressed for a cooldown period
• Each alert row has a View activity button that reveals the relevant folder (a user's home for growth alerts, the volume otherwise) in Finder

Alerts are saved locally and can also post to a webhook and show as notifications.

Future work

See docs/FUTURE_WORK.md. Highlights: fleet-scale deployment, first-class support for local model/OpenClaw workloads, retention and rollups, per-process I/O attribution, and trend-based health.

License

MIT — see LICENSE.