Skip to content

Instantly share code, notes, and snippets.

@tecnologer

tecnologer/README.md

Last active November 17, 2025 11:38
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save tecnologer/e306e503a762db549c50609f7f10e5e2 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save tecnologer/e306e503a762db549c50609f7f10e5e2 to your computer and use it in GitHub Desktop.
Download ZIP
Battery Alerts (Display-Centered Popups) for MacOS
Raw
README.md

Battery Alerts (Display-Centered Popups) for MacOS

This script provides a way to display battery alerts on MacOS using display-centered popups.

It could be configured as a LaunchAgent to run at user login or at specific intervals to monitor battery status and notify the user when the battery level is low or charged.

  • discharging and drops below a threshold
image
  • charging and reaches a target level.
image

Features

  • Display-centered popups for battery alerts
  • Configurable battery level thresholds for alerts
  • Easy to set up as a LaunchAgent
  • Optional auto-dismiss feature for popups

Requirements

It does not require any external dependencies, as it uses built-in MacOS tools like osascript for displaying popups.

Installation

  1. Copy the script to a desired location on your Mac.
  2. Make the script executable: 
    chmod +x /path/to/your/script.sh
  3. (Optional) Set up a LaunchAgent to run the script at login or specific intervals.
  4. Configure the battery level thresholds and auto-dismiss settings within the script as needed. Open ~/bin/battery-alert.sh and tweak: 
    LOW_BATTERY=20        # notify when discharging at/below this %
CHARGED_LEVEL=95      # notify when charging at/above this %
POPUP_TIMEOUT=8       # seconds; set 0 to require manual close
  5. Run the script manually or wait for the LaunchAgent to trigger it.
  6. Enjoy battery alerts displayed as popups on your Mac!

Example LaunchAgent Configuration

To create a LaunchAgent,

  1. Copy the file com.user.battery-alert.plist to ~/Library/LaunchAgents/
  2. Update the ProgramArguments path to point to your script location.
  3. Load the LaunchAgent: 
    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.user.batteryalert.plist
  4. Check the status: 
    launchctl list | grep batteryalert
  5. Optional: The interval can be adjusted by editing the StartInterval key in the plist file.
Raw
battery-alert.sh
#!/usr/bin/env bash
set -euo pipefail
# ---- Settings ----
LOW_BATTERY=25
CHARGED_LEVEL=95
POPUP_TIMEOUT=10 # seconds, 0 means no timeout
TITLE_LOW="Battery Low"
TITLE_CHARGED="Charging Level"
# ---- Requirements ----
need() { command -v "$1" >/dev/null 2>&1 || { echo >&2 "Error: $1 is not installed."; exit 1; } }
need osascript
need system_profiler
# ---- Helpers ----
show_popup() {
local title="$1"
local message="$2"
osascript <<EOF
tell application "System Events"
display dialog "$message" with title "$title" buttons {"OK"} default button "OK" giving up after $POPUP_TIMEOUT
end tell
EOF
}
read_battery_level() {
local level
local state
state=$(system_profiler SPPowerDataType | grep "Charging" | head -1 | awk '{print $2}')
level=$( system_profiler SPPowerDataType | grep 'State of Charge (%):' | awk '{print $5}')
echo "$state" "$level"
}
main() {
read -r ISCHARGING PERCENT < <(read_battery_level)
echo "Is Charging?: $ISCHARGING"
echo "Battery Level: $PERCENT%"
if [[ "$ISCHARGING" == "No" && "$PERCENT" -le "$LOW_BATTERY" ]]; then
show_popup "$TITLE_LOW" "⚠️ Battery level is at ${PERCENT}%. Please connect to a power source."
fi
if [[ "$ISCHARGING" == "Yes" && "$PERCENT" -ge "$CHARGED_LEVEL" ]]; then
show_popup "$TITLE_CHARGED" "🔋 Battery is charged to ${PERCENT}%. You can unplug the charger."
fi
}
main "$@"
Raw
com.user.batteryalert.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.user.batteryalert</string>
<key>ProgramArguments</key>
<array>
<string>PATH_OF_THE_SH_FILE</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>StandardOutPath</key>
<string>/tmp/battery-alert.log</string>
<key>StandardErrorPath</key>
<string>/tmp/battery-alert.err</string>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key>
<string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
</dict>
<key>StartInterval</key>
<integer>60</integer>
</dict>
</plist>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment