MacMonitor 🖥️

MacMonitor is a native, high-performance system monitor engineered specifically for Intel-based Macs running macOS 14 (Sonoma) and above. Built with a hybrid architecture of a lightweight SwiftUI presentation layer and low-level Objective-C/C kernel telemetry providers, it delivers deep visibility into the unique hardware characteristics of Intel MacBooks, iMacs, Mac minis, and Mac Pros.

---

Features & Telemetry Capabilities

⚡ Processor & Kernel Performance

• Per-Core Utilization: Real-time multi-core activity distribution (User %, System %, Nice %, Idle %) via Mach kernel host_processor_info.
• Clock Frequencies & Throttling: Active CPU core clock speeds (GHz), Turbo Boost state, and thermal frequency throttling indicators.
• Kernel Concurrency: Unix load averages (1m, 5m, 15m), normalized core saturation metrics, context switches/sec, system calls/sec, interrupts/sec, and page faults/sec.

❄️ Hardware Thermals & Fan Management

• CPU DTS Core Temperatures: Granular Intel Digital Thermal Sensor readings for every logical and physical core (TC0C–TC15C), CPU package die (TC0P/TC0D), and PECI interface.
• Multi-Fan Telemetry: Automated fan enumeration (FNum), live RPM tachometers (F{i}Ac), minimum/maximum RPM limits, target RPM, and fan stall detection.
• Chassis Component Matrix: Motherboard Platform Controller Hub (PCH), system heatsinks, memory DIMMs, power supply unit (PSU), Thunderbolt controllers, and ambient air sensors.

🧠 Memory & Virtual Memory

• Activity Monitor RAM Breakdown: Exact physical RAM distribution matching Activity Monitor (App Memory, Wired Memory, Compressed Memory, Cached Files, and Free Memory).
• Virtual Memory Swap: Total, used, available swap space, and real-time swap paging rates.
• Memory Pressure Level: Native Grand Central Dispatch memory pressure event notifications (Normal, Warning, Critical).

💾 Storage & Disk I/O

• Volumes & APFS Containers: Mounted internal SSDs, APFS snapshots, external Thunderbolt/USB volumes, with snapshot-aware purgeable space calculations.
• Real-Time Disk Throughput: Live read/write transfer rates (MB/s) and transaction rates (IOPS) via IOKit IOBlockStorageDriverStatistics.

🚦 Live Process Explorer & Inspector

• Process Activity Table: Live enumeration of active processes with PID, executable path, application icon, % CPU, RSS memory, compressed memory, and thread counts.
• Interactive Controls: Instant search, sorting, filtering by user/system tasks, and safe process termination (SIGTERM/SIGKILL).
• Process Drill-Down: Detailed inspection of individual process threads, Mach ports, open file descriptors, and network sockets.

🎮 Graphics (Dual-GPU & Integrated)

• Intel iGPU & AMD dGPU: Live engine utilization %, VRAM allocated/free, GPU core clock MHz, and temperature for Intel Iris/UHD Graphics and discrete AMD Radeon Pro GPUs.
• Dynamic GPU Switching: Seamless handling and power-down detection when macOS switches between integrated and discrete graphics.

🌐 Network & Socket Inspector

• 64-Bit Network Throughput: Instantaneous upload/download speeds (KB/s, MB/s), packet rates, and cumulative session totals via 64-bit BSD routing table counters (struct if_data64).
• Active Sockets: System-wide TCP/UDP connection explorer displaying local/remote IPs, ports, and connection states (LISTEN, ESTABLISHED, TIME_WAIT).

🔋 Battery, Power & Peripherals

• MacBook Battery Longevity: Charge %, health %, design vs maximum capacity, cycle count, instantaneous wattage, cell voltages, and AC adapter wattage.
• Display & Screen Brightness: Multi-display management with brightness monitoring and sliders via DisplayServices, refresh rates, resolution, and HDR status.
• Peripheral Bus Topology: USB hierarchy, Thunderbolt 3 chain link speeds, and PCIe expansion slot status (Mac Pro 2019).
• Audio HAL Status: Default input/output endpoints, sample rate (kHz), master volume scalars, and mute toggles.

📊 Presentation & Intelligence

• macOS Menu Bar Extra: Customizable, always-accessible status item with compact text or mini-sparklines.
• Quick-Glance Popover: Smooth, floating summary card for immediate hardware inspection.
• Swift Charts Engine: Rolling time-series graphs (1m to 1h) powered by high-performance in-memory ring buffers.
• Threshold Alerts Engine: Configurable thresholds (overheating, fan stall, memory exhaustion, low disk) with macOS Notification Center delivery and anti-spam cooldown logic.

---

Technical Architecture Overview

flowchart TD
    subgraph Hardware ["Intel Mac Hardware & Kernel"]
        SMC["AppleSMC (IOKit)"]
        MACH["Mach Kernel Host API"]
        PROC["libproc & BSD Sysctl"]
        IOK["IOKit Storage / GPU / USB"]
        CA["CoreAudio / DisplayServices"]
    end

    subgraph CoreEngine ["Low-Level Telemetry Engine (Objective-C/C)"]
        CLIENT["MMAppleSMCClient"]
        PROV["Telemetry Providers<br/>(MMCPUThermalProvider, MMCPUUsageProvider, etc.)"]
        COORD["MMTelemetryCoordinator<br/>(Dispatch Timer · QOS_CLASS_UTILITY)"]
    end

    subgraph Presentation ["Presentation Layer (SwiftUI & Swift)"]
        STORE["SystemTelemetryStore (@Observable · @MainActor)"]
        ALERT["AlertEngine"]
        VIEWS["SwiftUI Dashboard · MenuBarExtra · Charts"]
    end

    SMC <-->|"IOConnectCallStructMethod"| CLIENT
    CLIENT --> PROV
    MACH --> PROV
    PROC --> PROV
    IOK --> PROV
    CA --> PROV

    PROV -->|"Immutable Snapshots"| COORD
    COORD -->|"Async Dispatch"| STORE
    STORE -->|"Evaluate Rules"| ALERT
    STORE -->|"Reactive Binding"| VIEWS

For complete technical specifications, threading guarantees, and provider contracts, refer to ARCHITECTURE.md.

---

Project Structure

MacMonitor/
├── .gitea/
│   └── workflows/
│       └── build.yml               # Gitea Actions CI/CD workflow
├── Documentation/
│   ├── ARCHITECTURE.md             # Detailed system architecture & API design
│   ├── AGENTS.md                   # AI pair programming guidelines & rules
│   └── BUILD-PLAN.md               # Master deterministic roadmap & branch directory
├── Sources/
│   ├── Bridging/
│   │   ├── MacMonitor-Bridging-Header.h
│   │   ├── MMTelemetryProvider.h
│   │   └── MMTelemetryCoordinator.h/.m
│   ├── Providers/
│   │   ├── SMC/                    # AppleSMC client, thermal & fan providers
│   │   ├── CPU/                    # Mach processor load & kernel counters
│   │   ├── Memory/                 # VM statistics & memory pressure
│   │   ├── Storage/                # Volume manager & IOKit disk I/O
│   │   ├── Process/                # libproc explorer & thread inspector
│   │   ├── Graphics/               # IOAccelerator GPU telemetry
│   │   ├── Network/                # BSD routing sockets & PCB inspector
│   │   ├── Power/                  # AppleSmartBattery & electrical sensors
│   │   ├── Display/                # DisplayServices brightness & mode manager
│   │   └── Peripherals/            # USB, PCIe, and CoreAudio HAL providers
│   ├── UI/
│   │   ├── App/                    # MacMonitorApp entry point & MenuBarExtra
│   │   ├── Views/                  # Dashboard, popover, process table views
│   │   ├── Charts/                 # Swift Charts & ring buffer engine
│   │   └── ViewModels/             # SystemTelemetryStore & feature models
│   └── Intelligence/
│       └── AlertEngine.swift       # Threshold evaluations & UserNotifications
└── Tests/
    └── UnitTests/                  # Mocked SMC, Mach, and Provider unit tests

---

Building & Development Setup

Prerequisites

• macOS 14.0 (Sonoma) or newer.
• Xcode 15.0 or newer with command line tools installed.
• Intel Mac (x86_64) for native hardware testing (or an Intel macOS CI runner).

Build via Command Line

# Clone the repository
git clone https://git.i3omb.com/gronod/MacMonitor.git ~/Projects/MacMonitor
cd ~/Projects/MacMonitor

# Check out the active integration branch
git checkout develop

# Build Release binary for Intel x86_64
xcodebuild build \
  -scheme MacMonitor \
  -destination 'generic/platform=macOS,arch=x86_64' \
  -configuration Release \
  CODE_SIGNING_ALLOWED=NO

Run Automated Tests

xcodebuild test \
  -scheme MacMonitor \
  -destination 'platform=macOS,arch=x86_64' \
  CODE_SIGNING_ALLOWED=NO

---

Roadmap & Milestones

The project is broken down into 5 sequential delivery milestones with deterministic feature branches:

1. Milestone 1: Architecture Foundation & Hardware Abstraction (milestone/m1-foundation)
   • Core Objective-C bridging, MMTelemetryCoordinator, AppleSMC IOKit driver, and Gitea Actions CI.
2. Milestone 2: Primary System & Thermal Telemetry (milestone/m2-primary-telemetry)
   • CPU load, CPU core temps, fan speeds, RAM breakdown, storage volumes, and electrical power.
3. Milestone 3: Advanced Kernel, Process & Peripheral Telemetry (milestone/m3-advanced-telemetry)
   • Disk throughput (IOPS), Process Explorer, network bandwidth & sockets, GPU, battery, and peripherals.
4. Milestone 4: Presentation, Visuals & Menu Bar Integration (milestone/m4-presentation)
   • macOS 14 Menu Bar Extra, quick-glance popovers, display brightness control, and Swift Charts.
5. Milestone 5: Intelligence, Alerts & Hardening (milestone/m5-alerts-hardening)
   • Alert rule evaluation, Notification Center delivery, release packaging, and distribution.

Refer to BUILD-PLAN.md for the complete milestone schedule, parallel stage contracts, and exact branch names.

---

Contributing & Git Workflow

1. All features are developed in dedicated branches branching off their respective milestone branch (milestone/m<N>-...):

   git checkout milestone/m1-foundation
   git checkout -b feat/1-core-architecture
   

2. Commit messages must follow the Conventional Commits format (feat:, fix:, docs:, test:).
3. Open a Pull Request targeting the corresponding milestone branch. Ensure CI checks pass on Gitea Actions.

---

License

This project is licensed under the MIT License — see the LICENSE file for details.