{"id":48147656,"url":"https://github.com/graysoncadams/thermal-guardian","last_synced_at":"2026-04-04T17:01:51.428Z","repository":{"id":341907313,"uuid":"1171921424","full_name":"GraysonCAdams/thermal-guardian","owner":"GraysonCAdams","description":"macOS launchd agent that protects MacBook Pro from thermal damage in clamshell mode with Amphetamine","archived":false,"fork":false,"pushed_at":"2026-03-03T20:29:02.000Z","size":6,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T00:14:14.179Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/GraysonCAdams.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2026-03-03T18:58:27.000Z","updated_at":"2026-03-03T20:29:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/GraysonCAdams/thermal-guardian","commit_stats":null,"previous_names":["graysoncadams/thermal-guardian"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/GraysonCAdams/thermal-guardian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GraysonCAdams%2Fthermal-guardian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GraysonCAdams%2Fthermal-guardian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GraysonCAdams%2Fthermal-guardian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GraysonCAdams%2Fthermal-guardian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GraysonCAdams","download_url":"https://codeload.github.com/GraysonCAdams/thermal-guardian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GraysonCAdams%2Fthermal-guardian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31407391,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"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":[],"created_at":"2026-04-04T17:01:50.961Z","updated_at":"2026-04-04T17:01:51.342Z","avatar_url":"https://github.com/GraysonCAdams.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Thermal Guardian\n\nA macOS launchd user agent that protects your MacBook Pro from thermal damage\nwhen running in clamshell mode with [Amphetamine](https://apps.apple.com/app/amphetamine/id937984704)\npreventing sleep.\n\n## Problem\n\nWhen using Amphetamine to keep a MacBook Pro awake with the lid closed (e.g.,\nconnected to an external display), heat from the CPU and battery gets trapped\nbetween the display and keyboard. If battery temperature reaches dangerous\nlevels, this can accelerate battery degradation and potentially damage the\ndisplay panel adhesives.\n\n## Solution\n\nThermal Guardian runs every 60 seconds and checks three conditions:\n\n1. **Battery temperature** exceeds a configurable threshold (default: 50°C)\n2. **Lid is closed** (clamshell mode)\n3. **Amphetamine has an active session** (preventing sleep)\n\nWhen all three conditions are true simultaneously, it:\n\n1. Sends a macOS notification (visible on next wake)\n2. Ends the Amphetamine session\n3. Waits 3 seconds for cleanup\n4. Forces the system to sleep\n\nThis script **never starts** Amphetamine or any sessions — it only monitors and\nkills when dangerous conditions are detected.\n\n## Requirements\n\n- macOS (tested on macOS Sequoia / Apple Silicon M3 Pro)\n- [Amphetamine](https://apps.apple.com/app/amphetamine/id937984704) installed\n- No sudo required\n\n## Installation\n\n```bash\ngit clone https://github.com/GraysonCAdams/thermal-guardian.git ~/Repos/thermal-guardian\ncd ~/Repos/thermal-guardian\n./install.sh\n```\n\n## Uninstallation\n\n```bash\ncd ~/Repos/thermal-guardian\n./uninstall.sh\n```\n\n## Configuration\n\nEdit the variables at the top of `thermal-guardian.sh`:\n\n| Variable | Default | Description |\n|---|---|---|\n| `TEMP_THRESHOLD_C` | `50` | Battery temperature in °C that triggers protection |\n| `LOG_MAX_BYTES` | `1048576` | Max log file size before rotation (1 MB) |\n| `SLEEP_AFTER_END_SESSION` | `3` | Seconds to wait after ending Amphetamine session |\n\nAfter editing, changes take effect on the next 60-second cycle (no reload needed\nsince the script is re-executed each time by launchd).\n\n## Monitoring\n\n```bash\n# Watch live logs\ntail -f ~/Library/Logs/ThermalGuardian.log\n\n# Check if the agent is loaded\nlaunchctl list | grep thermal-guardian\n\n# Check current battery temperature\nioreg -r -n AppleSmartBattery -d 1 | grep '\"Temperature\"'\n\n# Manual test run\n./thermal-guardian.sh\n```\n\n## Log Files\n\n| File | Contents |\n|---|---|\n| `~/Library/Logs/ThermalGuardian.log` | Structured application logs (auto-rotated at 1 MB) |\n| `~/Library/Logs/ThermalGuardian-stdout.log` | launchd stdout capture |\n| `~/Library/Logs/ThermalGuardian-stderr.log` | launchd stderr capture |\n\n## How It Works\n\nThe script reads battery temperature from `ioreg` (AppleSmartBattery), which\nreports in decikelvin. For example, `3049` = 304.9 K = 31.75°C. The threshold\ncomparison is done in decikelvin using integer arithmetic to avoid floating-point\nissues in bash.\n\nAmphetamine is checked via `pgrep -x Amphetamine` before any AppleScript is sent,\nensuring the app is never launched just to query it.\n\n## Why 50°C?\n\n- Apple Silicon chips safely run 80–100°C under load, but **battery cells** are\n  the concern here — not the CPU\n- Li-ion battery degradation accelerates above 45°C and becomes dangerous above 55°C\n- With the lid closed, the battery's heat has nowhere to go — normally the display\n  acts as a heatsink\n- 50°C gives a meaningful margin above normal clamshell temps (~35–42°C) while\n  triggering well before the danger zone for battery chemistry\n- This avoids false positives during normal heavy workloads while catching the\n  genuinely dangerous trapped-heat scenario\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraysoncadams%2Fthermal-guardian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraysoncadams%2Fthermal-guardian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraysoncadams%2Fthermal-guardian/lists"}