gronodandDevin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
a533ee1f9f
The generic 'generic/platform=macOS,arch=x86_64' destination is rejected by
the runner's Xcode ("Any Mac" does not support the arch option), failing the
release-package build. Match the working build-and-test destination.
Also correct the same specifier in README.md and AGENTS.md.
Generated with [Devin](https://devin.ai)
Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
210 lines
11 KiB
Markdown
210 lines
11 KiB
Markdown
# MacMonitor 🖥️
|
||
|
||
[](https://www.apple.com/macos/sonoma/)
|
||
[](https://en.wikipedia.org/wiki/X86-64)
|
||
[]()
|
||
[](https://git.i3omb.com/gronod/MacMonitor/actions)
|
||
[](LICENSE)
|
||
|
||
**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
|
||
|
||
```mermaid
|
||
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](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
|
||
```bash
|
||
# 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 'platform=macOS,arch=x86_64' \
|
||
-configuration Release \
|
||
CODE_SIGNING_ALLOWED=NO
|
||
```
|
||
|
||
### Run Automated Tests
|
||
```bash
|
||
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](https://git.i3omb.com/gronod/MacMonitor/milestone/18)** (`milestone/m1-foundation`)
|
||
- Core Objective-C bridging, `MMTelemetryCoordinator`, `AppleSMC` IOKit driver, and Gitea Actions CI.
|
||
2. **[Milestone 2: Primary System & Thermal Telemetry](https://git.i3omb.com/gronod/MacMonitor/milestone/19)** (`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](https://git.i3omb.com/gronod/MacMonitor/milestone/20)** (`milestone/m3-advanced-telemetry`)
|
||
- Disk throughput (IOPS), Process Explorer, network bandwidth & sockets, GPU, battery, and peripherals.
|
||
4. **[Milestone 4: Presentation, Visuals & Menu Bar Integration](https://git.i3omb.com/gronod/MacMonitor/milestone/21)** (`milestone/m4-presentation`)
|
||
- macOS 14 Menu Bar Extra, quick-glance popovers, display brightness control, and Swift Charts.
|
||
5. **[Milestone 5: Intelligence, Alerts & Hardening](https://git.i3omb.com/gronod/MacMonitor/milestone/22)** (`milestone/m5-alerts-hardening`)
|
||
- Alert rule evaluation, Notification Center delivery, release packaging, and distribution.
|
||
|
||
Refer to [BUILD-PLAN.md](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>-...`):
|
||
```bash
|
||
git checkout milestone/m1-foundation
|
||
git checkout -b feat/1-core-architecture
|
||
```
|
||
2. Commit messages must follow the [Conventional Commits](https://www.conventionalcommits.org/) 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](LICENSE) file for details.
|