Native macOS monitoring, workload analysis, thermal forecasting, and guarded fan control in one focused application.
Download · Build from source · Documentation · Report a problem
Thermal Intelligence looks beyond a momentary CPU percentage. It observes how long workloads remain active, how system temperature responds after a delay, whether a pattern recurs, and how much cooling is already being applied. The result is a compact dashboard that answers three useful questions:
- What is putting sustained pressure on this Mac?
- Where is the temperature likely to move next?
- Why did the cooling policy make its current decision?
All product telemetry and history stay on the Mac. There is no account, advertising, analytics SDK, cloud dashboard, or automatic log upload.
| Area | Capability |
|---|---|
| Monitoring | Temperature, thermal state, CPU and memory pressure, power-related signals, process impact, and actual fan RPM where available |
| Workload insight | Current impact, sustained impact, thermal association, recurring workload evidence, and a distinct System/Unknown contribution |
| Cooling | Apple System, Calm, Balanced, Aggressive, System Max, Cool Now, and editable custom temperature-to-speed curves |
| Smart control | Smoothed signals, heat debt, forecast-assisted demand, hysteresis, minimum hold times, and explainable reason codes |
| History | Synchronized temperature, load, fan RPM, and cooling-demand charts with range selection, pan, zoom, inspection, and reset |
| Diagnostics | Privacy-filtered JSON Lines logs, bounded size rotation, in-app log access, and explicit ZIP export through the macOS share sheet |
| Resilience | A regular reopenable app window, menu-bar popover, typed XPC boundaries, command retries, lease expiry, heartbeat recovery, and Apple-control restoration |
- Apple System leaves fan decisions entirely to macOS.
- Calm waits longer before adding cooling and prioritizes acoustics.
- Balanced is the everyday temperature/noise compromise.
- Aggressive starts earlier and keeps a higher cooling floor during sustained or recurring heat.
- System Max asks the Mac's own control path for its maximum cooling state.
- Cool Now temporarily applies maximum cooling, with visible acquisition, verification, active, and recovery states.
- Custom profiles use a validated, non-decreasing curve. Points can be dragged visually or edited numerically for precision and accessibility.
Selecting a profile does not mean the application must immediately take manual control. When additional cooling is unnecessary, the selected policy remains ready while macOS continues to manage the fans.
Monitoring is designed to remain useful on supported modern macOS versions, including fanless Macs. Fan control is deliberately narrower:
- fan presence is detected at runtime;
- fanless Macs never install or activate the privileged control service;
- an unknown hardware fingerprint cannot reach the write path;
- the App sends policy preferences to the Agent, never hardware commands;
- the Agent sends only bounded normalized demand to the Helper;
- the privileged Helper owns the lease, tachometer checks, restore behavior, and the model-specific hardware adapter;
- stale commands, lost ownership, invalid sensors, sleep, logout, or process failure return control to Apple whenever the hardware path permits it.
The current public fan-control adapter is model-scoped. A Mac can therefore be fully supported for monitoring while remaining in Apple-controlled cooling mode. See Architecture and Troubleshooting for the exact behavior.
Important: Fan control changes hardware behavior. Keep macOS and firmware current, do not bypass compatibility checks, and use Apple System if sensor or fan feedback appears abnormal.
flowchart LR
App["ThermalApp<br/>SwiftUI + AppKit"]
Agent["ThermalAgent<br/>metrics · history · policy"]
Helper["FanSafetyHelper<br/>lease · verification · restore"]
Hardware["Model-scoped<br/>fan adapter"]
App -->|"typed, versioned XPC"| Agent
Agent -->|"bounded demand"| Helper
Helper -->|"validated operations"| Hardware
App -. no direct access .-> Hardware
Agent -. no raw SMC writes .-> Hardware
The repository is split into small Swift Package Manager targets. Domain logic, collectors, persistence, IPC, policy, logging, UI, safety, and model adapters have independent ownership and focused tests. No executable acts as a shared god object or global service locator.
- Download the latest notarized
Thermal Intelligence Installer.pkgfrom GitHub Releases or nibtip.tech. - Open the package and follow the standard macOS Installer flow.
- Launch Thermal Intelligence from Applications.
- Approve background service registration when macOS asks. Privileged fan control is requested separately and only on an eligible Mac.
Release packages are signed with Developer ID, notarized by Apple, stapled, and checked with Gatekeeper before publication.
Requirements:
- macOS 13 or newer;
- Xcode 26.6 or a compatible Swift 6.2+ toolchain;
- standard Apple command-line developer tools.
git clone https://github.com/NibTipLabs/thermal-intelligence.git
cd thermal-intelligence
./scripts/verify.sh --quick
./scripts/build-app.sh
open "dist/Thermal Intelligence.app"The local build is ad-hoc signed and intended for development. Developer ID distribution, notarization, stapling, and model-specific hardware validation are separate release steps. See Building.
Sources/
├── ThermalApp/ application composition root
├── ThermalAgent/ monitoring and policy composition root
├── FanSafetyHelper/ privileged safety composition root
├── AppFeatures/ dashboard, popover, settings, charts
├── SystemMetrics/ read-only macOS collectors
├── ThermalCore/ forecasting and cooling policy
├── TelemetryStore/ bounded SQLite history
├── ThermalLogging/ redaction, rotation, diagnostics export
├── AppAgentIPC/ App ↔ Agent transport
├── AgentHelperIPC/ Agent ↔ Helper transport
└── HelperSafetyCore/ lease, restore, and independent safeguards
Tests/ focused tests mirroring production targets
Installer/ standard macOS package resources and scripts
Resources/ app metadata, localization, icons, service plists
docs/ architecture, operations, testing, and policies
scripts/ reproducible build and verification entry points
- Architecture and module boundaries
- Security architecture
- Code documentation standard
- Build guide
- Test strategy
- Logging and diagnostics
- Installer design
- Distribution and release
- Troubleshooting
- Security policy
- Privacy policy
- Version history
Focused issues, tests, documentation, accessibility improvements, and reviewed code changes are welcome. Changes to privileged control, compatibility, or restore behavior require corresponding tests and explicit safety review. Please read CONTRIBUTING.md before opening a pull request.
Thermal Intelligence is available under the MIT License. Third-party attributions are listed in THIRD_PARTY_NOTICES.md.
Developed by Nikolai Pozdnyakov at NibTip Labs · nibtip.tech · Made in Kyrgyzstan 🇰🇬