mac-stats AGENTS.md

MacStats — Agent Guide

Native macOS menu bar system monitor. Inspired by iStat Menus. Personal use, not App Store.

Product context

• Replace macOS Activity Monitor for quick glances at CPU/RAM/Disk/Network/Battery.
• Menu bar first: compact metrics always visible; dropdown for detail.
• Per-process tops (CPU/RAM/Disk) so the user can spot hogs without opening Activity Monitor.
• Target audience: the repo owner. No localization, no onboarding, no telemetry.

Non-goals

• App Store distribution (no sandboxing, no notarization pipeline).
• Cross-platform. macOS 13+ only (uses modern SwiftUI APIs + IOKit).
• SMC voltage / current sensors. Keys vary per chip family and aren't mapped. (Fan RPM is supported via the SMC client added in v0.3.0; CPU/GPU/SOC temperatures via IOHID.)
• Threshold-based notifications and world clocks / weather (intentionally out of scope vs iStat Menus parity).

Stack

• Swift 6.3 toolchain + Swift 6 strict concurrency language mode (.swiftLanguageMode(.v6) in Package.swift). Every Sample struct is Sendable.
• SwiftUI + AppKit (NSStatusItem for menu bar, SwiftUI for content).
• Swift Package Manager (no Xcode project). Package.swift is the source of truth.
• macOS 13+ deployment target.
• No external dependencies.

Build / run

./Scripts/run.sh           # debug bundle + launch
./Scripts/bundle.sh release  # release .app
swift build -c debug       # compile only
pkill -x MacStats          # kill running instance

run.sh wraps the SPM binary into a proper .app with Info.plist (sets LSUIElement=true so the app has no Dock icon). bundle.sh also copies Resources/AppIcon.icns into the bundle and wires CFBundleIconFile = AppIcon so Finder / About show the MacStats icon.

When iterating, kill before rebuild (pkill -x MacStats). If a change looks like it didn't apply, run swift package clean — SPM has occasionally served stale binaries in this repo.

Architecture

Sources/MacStats/
├── MacStatsApp.swift            # @main, AppDelegate; spawns StatusBarController + MainWindowController; pkill orphan nettops on launch/quit
├── StatusBarController.swift    # owns N NSStatusItems (one per metric) + shared NSPopover; retains detail + nettop sampling while popover is shown
├── MainWindowController.swift   # NSWindowController hosting MainWindowView (sidebar + detail panes)
├── SystemStats.swift            # @MainActor ObservableObject + actor StatsSampler; refcounted detail/full-process/nettop tiers; ThermalLevel enum
├── DisplayPreferences.swift     # BarMetric enum + which metrics show in menu bar (UserDefaults-backed)
├── MenuBarSnapshot.swift        # frozen copy of selected metrics for the status bar
├── Formatters.swift             # byte/rate/percent formatting
├── ProcessKill.swift            # confirm-and-kill helper used by leader rows
├── Monitors/                    # stateless-ish samplers, one per hardware domain
│   ├── CPUMonitor.swift         # aggregate host_statistics + per-core host_processor_info + getloadavg
│   ├── MemoryMonitor.swift      # host_statistics64 HOST_VM_INFO64 + vm.swapusage + swap-in/out rates
│   ├── NetworkMonitor.swift     # getifaddrs + if_data; per-iface IPs gated to detail tier
│   ├── WiFiMonitor.swift        # CoreWLAN: SSID, RSSI, channel/band/width, txRate
│   ├── DiskMonitor.swift        # IOKit IOBlockStorageDriver + per-volume capacity + diskutil SMART
│   ├── BatteryMonitor.swift     # IOPowerSources + AppleSmartBattery registry
│   ├── ProcessMonitor.swift     # libproc: proc_listpids + PROC_PIDTASKALLINFO + rusage
│   ├── NetworkProcessMonitor.swift  # spawns `nettop` and parses per-process bytes_in/out
│   ├── TemperatureMonitor.swift # private IOHIDEventSystemClient: CPU/GPU/SOC thermal sensors
│   ├── GPUMonitor.swift         # IOAccelerator → PerformanceStatistics utilization + vRAM
│   ├── SMCClient.swift          # AppleSMC user client (kSMCHandleYPCEvent dispatch)
│   ├── FanMonitor.swift         # SMC F<i>Ac/Mn/Mx/Tg/ID → FanInfo[]
│   └── SamplingMath.swift       # shared delta / rate helpers (handles counter rollover)
└── Views/
    ├── SingleMetricLabel.swift     # one metric in the menu bar (icon above compact value)
    ├── MenuBarContentView.swift    # dropdown / popover content (header + sections + prefs + quit)
    ├── MenuBarPrefsView.swift      # 3-col grid of checkboxes for which metrics show in bar
    ├── TopProcessesView.swift      # tabbed top processes (CPU/RAM/Disk/Network/Energy)
    ├── MainWindowView.swift        # sidebar nav (Overview / Hardware / Activity)
    ├── PaneKit.swift               # shared pane primitives: PaneHeader, MetricCard, AreaSpark, DualAreaSpark, ScaleHelper
    └── Panes/
        ├── DashboardPane.swift     # at-a-glance card grid (cpu, mem, network, disk, battery, temperature)
        ├── MetricPanes.swift       # CPU / GPU / Memory / Disk / Network / Battery / Temperature / Fans + LeaderList
        └── ProcessesPane.swift     # full filterable / sortable process table

Resources/
└── AppIcon.icns                # built via iconutil from design_handoff_macstats_logo/

design_handoff_macstats_logo/   # canonical icon source (SVG + sized PNGs + README)