{"id":47300602,"url":"https://github.com/angristan/MacThrottle","last_synced_at":"2026-03-31T06:00:49.165Z","repository":{"id":329255621,"uuid":"1117406277","full_name":"angristan/MacThrottle","owner":"angristan","description":"Menu bar app to know when your Mac is thermal throttling","archived":false,"fork":false,"pushed_at":"2026-02-13T21:27:31.000Z","size":1382,"stargazers_count":590,"open_issues_count":9,"forks_count":20,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-30T05:39:39.348Z","etag":null,"topics":["apple","apple-silicon","mac","macbook","macbook-air","macos","swift","swiftui","thermal","thermal-throttling"],"latest_commit_sha":null,"homepage":"https://stanislas.blog/2025/12/macos-thermal-throttling-app/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/angristan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-16T09:15:32.000Z","updated_at":"2026-03-29T23:32:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/angristan/MacThrottle","commit_stats":null,"previous_names":["angristan/macthrottle"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/angristan/MacThrottle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angristan%2FMacThrottle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angristan%2FMacThrottle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angristan%2FMacThrottle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angristan%2FMacThrottle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/angristan","download_url":"https://codeload.github.com/angristan/MacThrottle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angristan%2FMacThrottle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31223291,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-31T04:08:55.938Z","status":"ssl_error","status_checked_at":"2026-03-31T04:08:47.883Z","response_time":111,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple","apple-silicon","mac","macbook","macbook-air","macos","swift","swiftui","thermal","thermal-throttling"],"created_at":"2026-03-17T01:38:19.998Z","updated_at":"2026-03-31T06:00:49.159Z","avatar_url":"https://github.com/angristan.png","language":"Swift","readme":"# MacThrottle\n\n[![GitHub Release](https://img.shields.io/github/v/release/angristan/MacThrottle)](https://github.com/angristan/MacThrottle/releases)\n[![CI](https://github.com/angristan/MacThrottle/actions/workflows/ci.yml/badge.svg)](https://github.com/angristan/MacThrottle/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![macOS](https://img.shields.io/badge/macOS-15+-blue)](https://github.com/angristan/MacThrottle)\n[![Swift](https://img.shields.io/badge/Swift-6-orange)](https://swift.org)\n\nA lightweight macOS menu bar app that monitors thermal pressure and alerts you when your Mac is being throttled. No admin privileges required.\n\n![screenshot](./assets/screenshot.png)\n\n## Features\n\n- Displays thermal pressure state in the menu bar using different thermometer icons\n- Shows CPU core temperature (reads directly from SMC)\n- Shows fan speed percentage (on Macs with fans)\n- History graph showing thermal state, temperature, and fan speed over the last 10 minutes\n- Statistics showing time spent in each thermal state\n- Configurable notifications:\n  - When heavy throttling begins\n  - When critical throttling occurs\n  - When throttling stops (recovery)\n  - Optional notification sounds\n- Launch at Login option\n- No helper daemon or admin privileges required\n\n## Thermal States\n\n| Icon                   | State    | Description               |\n| ---------------------- | -------- | ------------------------- |\n| `thermometer.low`      | Nominal  | Normal operation          |\n| `thermometer.medium`   | Moderate | Elevated thermal pressure |\n| `thermometer.high`     | Heavy    | Active throttling         |\n| `thermometer.sun.fill` | Critical | Severe throttling         |\n\n## Installation\n\n### Homebrew (recommended)\n\n```bash\nbrew tap angristan/tap\nbrew install --cask macthrottle\n```\n\n### Download from Releases\n\nSince the app is not signed, Gatekeeper may block it on first launch. You can remove the quarantine attribute manually, or build it locally with Xcode to sign it with your own certificate.\n\n1. Download the latest `.dmg` from [Releases](https://github.com/angristan/MacThrottle/releases)\n2. Open it, and drag `MacThrottle.app` to your Applications folder\n3. Remove quarantine attribute: `xattr -r -d com.apple.quarantine /Applications/MacThrottle.app`\n4. Open the app\n\n### Build Locally\n\nBuilding locally automatically signs the app with your development certificate, avoiding Gatekeeper issues.\n\n```bash\n# Clone the repo\ngit clone https://github.com/angristan/MacThrottle.git\ncd MacThrottle\n\n# Build with Xcode\nxcodebuild -project MacThrottle.xcodeproj \\\n  -scheme MacThrottle \\\n  -configuration Release \\\n  -derivedDataPath build\n\n# Run the app\nopen build/Build/Products/Release/MacThrottle.app\n```\n\nOr open `MacThrottle.xcodeproj` in Xcode and press `Cmd+R` to build and run.\n\n## How It Works\n\n### Thermal Pressure\n\nMacThrottle reads thermal pressure using the Darwin notification system ([`notify_get_state`](https://developer.apple.com/documentation/darwinnotify/notify_get_state)), specifically the `com.apple.system.thermalpressurelevel` notification. The system reports 5 levels (nominal, moderate, heavy, trapping, sleeping), but MacThrottle consolidates the last two into \"critical\" since they're rarely reached in practice. Heavy is where throttling really kicks in.\n\n\u003e **Note:** This notification name is not publicly documented by Apple. It comes from the private [`OSThermalNotification.h`](https://github.com/tripleCC/Laboratory/blob/a7d1192f25d718e3b01a015ca35bfcef4419e883/AppleSources/Libc-1272.250.1/include/libkern/OSThermalNotification.h#L44-L48) header (as `kOSThermalNotificationPressureLevelName`) and has been available since macOS 10.10. See [Thermals and macOS](https://dmaclach.medium.com/thermals-and-macos-c0db81062889) for more details on macOS thermal APIs.\n\u003e You can see it implemented [in Bazel for example](https://github.com/bazelbuild/bazel/blob/83bddd49aae9e42b4aff1c79c4f437a31b9aec8c/src/main/native/darwin/system_thermal_monitor_jni.cc#L27).\n\n#### Why not `ProcessInfo.thermalState`?\n\nmacOS provides [`ProcessInfo.thermalState`](https://developer.apple.com/documentation/foundation/processinfo/thermalstate-swift.enum) as a public API, but it has limited granularity (only 4 states vs the 5 actual pressure levels):\n\n| `ProcessInfo.thermalState` | Actual Pressure Level |\n| -------------------------- | --------------------- |\n| nominal                    | nominal               |\n| **fair**                   | **moderate**          |\n| **fair**                   | **heavy**             |\n| serious                    | trapping              |\n| critical                   | sleeping              |\n\nThe `moderate` and `heavy` states both map to `fair` in `ProcessInfo.thermalState`, but the difference is significant: `heavy` is when throttling really kicks in. MacThrottle provides this granularity.\n\n### Temperature Reading\n\nMacThrottle displays temperature alongside thermal pressure. Reported temperature is the maxmium of all CPU/GPU core temperatures.\n\nIt's using two methods:\n\n#### SMC (Primary)\n\nThe **System Management Controller (SMC)** is a hardware chip in every Mac that manages thermal sensors, fans, and power. MacThrottle reads directly from the SMC via IOKit to get actual CPU core temperatures.\n\n- Reads chip-specific sensor keys (different for M1, M2, M3, etc)\n- Provides accurate per-core temperature readings\n- Based on the approach used by [Stats](https://github.com/exelban/stats)\n\n#### IOHIDEventSystem (Fallback)\n\nIf SMC reading fails, MacThrottle falls back to the **IOHIDEventSystem** private API:\n\n- Reads temperature events from PMU (Power Management Unit) sensors\n- Simpler but less granular: returns aggregate \"tdie\" temperatures rather than per-core values\n- May report slightly different (typically lower) values than SMC\n\nThe displayed temperature is the maximum reading across all available CPU sensors.\n\n### Fan Speed\n\nOn Macs with fans, MacThrottle reads fan speed from the SMC using standard fan keys (`FNum` for count, `F0Ac`/`F1Ac` for actual RPM, `F0Mx`/`F1Mx` for maximum RPM). The speed is displayed as a percentage of maximum capacity and shown as a dashed cyan line on the history graph.\n\nFanless Macs (like MacBook Air) won't show fan data or the \"Show Fan Speed\" toggle.\n\n## Requirements\n\n- macOS 15.0+ (Sequoia)\n","funding_links":[],"categories":["Swift"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangristan%2FMacThrottle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fangristan%2FMacThrottle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangristan%2FMacThrottle/lists"}