A lightweight macOS menu bar app for monitoring battery status and controlling charging on Apple Silicon Macs.
- Real-time battery stats - percentage, cycle count, health, temperature, raw charge, and battery age, plus wattage (adapter / battery / system), voltage (adapter / battery), and current (adapter / battery); clicking a card that has a second unit switches it, and the temperature starts in the unit macOS is set to (see Card Units)
- Charge control - pause and resume charging via SMC
- Auto charge - configurable upper/lower bounds to keep your battery in an optimal charge range; custom bounds are the paid feature, and a free license runs the default 40 to 60% range
- Micro-charge prevention - inhibits charging between bounds after restart; only charges from below the lower bound or on explicit user request
- Sleep-safe charging - an in-progress charge never overshoots the upper bound while the Mac sleeps: between the bounds it pauses just before sleep and resumes on wake; below the lower bound the Mac is kept awake until the charge completes
- Charge to upper bound - explicitly allow charging from the current level to the upper bound
- Charge to full - one-shot full charge without touching the configured bounds; normal management resumes when full
- Discharge to upper bound - optionally drain the battery to the target level while on AC power
- Health check - periodically verifies SMC state matches expected values, and re-applies the expected charging state if it drifted; while macOS runs its own calibration charge, which overrides the macOS charge limit, it reports suspended instead of a pass
- macOS 27 support - on firmware that no longer exposes the charge-inhibit key, the app holds the battery through macOS's own charge limit instead, with the same bounds and toggles (see Firmware without CHTE below). macOS still charges the battery to full every few weeks to calibrate its gauge and ignores the limit meanwhile; the panel says so while that runs, says once the battery is full that macOS lifts the override by the clock, about 12 hours after the charge began, and the hold resumes at the level reached
- In-app updates - checks the Homebrew cask for new versions about once a day; a small blue badge dot on the menu bar icon signals a pending update, and clicking Update to X in the panel downloads, verifies, installs, and relaunches
- Menu bar icon - battery shape with live charge level and animated fill when charging or discharging; hovering it shows the current charge and status (e.g. "85% — Charging — 32m to 80%"); the percent readout beside it can be hidden (Settings → Percent in Menu Bar) for a narrower menu bar footprint; a running Keep Awake session shows to the left of the battery, as its symbol and the time it has left (see Keep Awake)
- Pin it, or make it a window - pin the panel to keep it open while you work, or drag it off the menu bar and it becomes a window like any other: title bar, close and minimize buttons, a Dock icon and Ampere's own menu bar for as long as it is open, and it comes back where it was after a restart (see The Panel as a Window)
- Settings window - the settings have a window of their own, grouped by subject, opened from Settings… in the panel footer or with ⌘, (see Settings Window)
- Keep awake - optionally prevent idle sleep while on AC power, for a set duration or until turned off (the Keep Awake row on the panel); a standard power assertion, so it needs no admin rights and is auto-released on quit or crash. The session's Keep Display On option keeps the display on as well, so the Mac does not lock on its own; turning that on asks for Touch ID or your password. A running session shows in the menu bar: a cup and the time left, or, while the display is kept on, a white display on an accent-colored badge. Keep Awake is a paid feature: on a free license the row shows a lock and an Unlock… button, which opens the registration window, in place of its controls, and a running session ends if the paid license lapses
- Launch at login - start automatically when you log in
- Registration - Ampere needs a license to control charging: a free license, asked for in the registration window with your name and email address (the key is emailed to you, never shown in the app, and registered like a bought one), or a paid license bought at amperebattery.app. Until one is registered the app shows only its registration window, with Quit as the other way out. A key registers as many Macs at once as the license server says for it (a free license holds one), and the registration window says how many and how many are in use ("Macs in use: 2 of 5"): a one-Mac key moves to whichever Mac registers it, and a fuller key takes further Macs until it is full. The registration is re-verified against the license server about once a day and each time the registration window opens — network failures never clear it — and Deregister This Mac in the registration window takes this Mac off the key. A free license runs the default 40 to 60% range; a paid license unlocks custom charge bounds and Keep Awake. Paid licenses registered before the free license existed are unchanged.
- macOS 15 (Sequoia) or later
- Apple Silicon Mac
- Admin privileges (for charge control features)
- A license for charge control, free or paid (battery information needs none; see Charge Bounds and Registration below)
macOS 14 is not supported: the Homebrew cask and the in-app updater refuse it, and a copy of 0.0.65 or earlier already installed there still opens but gets no further updates (see Updates). macOS 15 is supported, with one caveat about charge control. Ampere needs either the CHTE key in the firmware or the macOS charge limit, and macOS 15 has only the first: the firmware that its later security updates install has no CHTE key, and the charge limit Ampere falls back on without it arrived in macOS 26.4. Ampere checks for both when it takes charge control and, finding neither, monitors the battery only and says so on the panel (see Firmware without CHTE below). Ampere is developed on macOS 26 and 27.
brew tap az-code-lab/taps
brew install --cask ampereDownload the latest .dmg from the GitHub Releases page, open it, and drag Ampere.app to your Applications folder.
Pausing/resuming charging requires root access to write to the SMC. Ampere handles this as follows:
- On launch - once a license is registered (see Charge Bounds and Registration below), the app installs (or updates) its helper binary; an unregistered copy shows only its registration window and asks for nothing until you register, at which point the same steps run. If the helper is missing, outdated, or not authorized for the current account, macOS prompts for your admin password. If cancelled at launch, the app exits; cancelled right after registering, charge control stays on hold until the next charge-control action asks again. If the helper cannot be installed at all, for example because the helper directory is writable by other users, the alert explains why instead of asking for a password.
- Setup - a compiled helper binary (
SMCWriter) is installed at/Library/PrivilegedHelperTools/az-ampere-smc(owned by root), along with a sudoers rule at/etc/sudoers.d/az-amperethat allows passwordless execution of the helper. The rule is pinned to the helper's SHA-256 digest. The helper and every directory leading to it are checked for root ownership, write permissions, ACLs, and symlinks, preventing replacement by an ordinary app. - Subsequent launches - the helper and the current account's passwordless authorization are verified at startup. If both are current, no password is needed. After a Homebrew upgrade, the new helper is installed automatically (one password prompt).
- Cleanup job - once this account can run the helper, the app registers a root launchd job (
/Library/LaunchDaemons/com.az-code-lab.ampere.cleanup.plist) that watches the installedAmpere.app. Registration goes through the same passwordless rule, so it never prompts. If the bundle stays gone for two minutes (the job looks for it every five seconds from the moment it is first seen missing, so abrew upgrade, which quits the app and replaces the bundle within seconds, never comes near the deadline) and no copy of Ampere is running, the job has the helper restore charging and sleep settings and remove the helper, the sudoers rule, the state directory, the job itself, and every account's preferences, caches, and saved window state, so dragging the app to the Trash orbrew uninstallleaves nothing behind (see Uninstall). macOS shows a one-time "Background Items Added" notice when the job is first registered and lists it under Ampere in System Settings > General > Login Items & Extensions. MovingAmpere.appre-registers the job at the next launch; if the old location stays empty for two minutes before that launch, the helper is uninstalled and the next launch asks for the password again.
Upgrading from the former /usr/local/bin/az-ampere-smc location migrates the helper during that same administrator prompt. The replacement is verified before installation, restores the previous session's charging and sleep state, and retires the old helper and watchdogs. A restore failure does not block the installation; the app's launch cleanup and the watchdog retry it. Preferences, charge bounds, and registration stay intact; no manual migration is needed.
Note: Admin access is granted per macOS user account: the sudoers file holds one line per account that has granted it. Another account on the same Mac is asked for its password once, after which both stay authorized, and an upgrade refreshes every line so only the first account to launch the new version is prompted. Revoke removes only the current account's line and deletes the helper once no account remains. Only one running copy of Ampere manages charge control at a time: with fast user switching, a copy launched while another account's copy is already running shows battery information but stands by, and takes over once that copy quits.
When enabled, the app automatically manages charging between configurable bounds:
- Below lower bound - starts charging, continues until the upper bound is reached
- Between bounds - holds (charging inhibited); use Charge to Upper Bound to explicitly start charging
- Above upper bound - inhibits charging; use Discharge to Upper Bound to actively drain to the target
Ampere needs a license to run, and there are two kinds. A free license is a name and an email address away: in the registration window (it opens by itself until a license is registered; afterwards Manage… on the License row of the settings window opens it), enter both and press Get Free License. The key is emailed to that address and never shown in the app, so entering it under Registration Key with the same address and pressing Register proves the address is yours. One free license per email address and per Mac; it never expires, and a mistyped address costs nothing, since the next request replaces a key that never registered a Mac. No email? Check the spam folder, or press Get Free License again: the key is emailed again, a few times an hour at most. A paid license is bought at amperebattery.app and registered the same way. To move from a free license to a paid one on the same Mac, press Deregister This Mac first, then register the paid key with the email it was issued to.
Until a license is registered, Ampere shows its registration window and nothing else: the menu bar icon is an empty outline that opens the window, the panel is not available, the window cannot be closed, and the choice is to register or to press Quit Ampere. Nothing is written to the SMC meanwhile, and no helper is installed or asked for. Custom charge bounds are the paid feature. A free license runs the default 40 to 60% range: the slider still shows the bounds, but the draggers are locked (their tooltips say so), and an Unlock… button beneath the slider opens the registration window. Everything else in charge control, including auto charge itself, micro-charge prevention, charge and discharge to upper bound, and charge to full, works the same on a free license. Keep Awake is the other paid feature (see Keep Awake).
Registering a paid key unlocks the draggers immediately. If a paid registration lapses (deregistered in the registration window, released under My Licenses, replaced by another Mac on a one-Mac key, or the daily verify reporting the license ended or revoked), both bounds return to 40 to 60% at once and the draggers lock again, and a running Keep Awake session ends; the state machine treats the bound change like any other, so a charge already past 60% is inhibited on the next poll. The reset is also applied at launch, so a custom range persisted by a lapsed registration never resurfaces after a restart. When a registration of either kind lapses, charge control goes on hold: whatever the session had in force is put back the way quitting puts it (one helper restore, which allows charging, ends a discharge, and restores the sleep settings and the macOS charge limit; a restore that fails is retried every two minutes and once more at quit), while the Auto Charge setting, the bounds and an in-progress charge-to-upper or charge-to-full intent are kept, so registering again, even after a restart, resumes exactly where the copy was. One of Ampere's own password prompts being open at that moment changes none of this (see Password Prompts): the restore puts back what was frozen for the prompt, at once, and a helper install that then lands on the hold applies nothing and runs no health check; the watchdog its setup started is retired by a restore of its own, and so is a restore the hold tried before the grant existed. A license registered again before that prompt is answered takes charge control once it is, without a second prompt; until then the status line says it is waiting for the prompt, not for a license. After Revoke there is nothing to put back, since Revoke restores first and the account can no longer run the helper, so a registration that lapses then asks the helper for nothing. Network failures never lapse a registration, so an offline Mac keeps its license and its bounds. Paid licenses registered by builds before the free license existed stored no kind and are read as paid, so the update changes nothing for them.
Registering sends the email, the key, the Mac's device serial, the app version, and the macOS version to the license server; the verify, about once a day and each time the registration window opens, sends the same without the key. Asking for a free license sends the name, the email address, the device serial, the app version and the product, and the server answers with the key's terms, never the key. Every call also names the product, so the server hands the app only Ampere keys: another app's key answers "Invalid license key" instead of taking one of that key's places for this Mac. The macOS version is there to show which systems registered Macs actually run, which is what decides the oldest macOS the app has to keep supporting. An unregistered copy sends none of this until you ask for a free license or register: it never contacts the license server otherwise, and its only network traffic is the update check against the public Homebrew cask, plus the download from GitHub Releases when you click Update.
How many Macs a key registers at once is a term of the key, copied from the license model it was sold under, so keys sold at different times can differ; a free license always holds one. The server returns the count with every registration and every verify. The app keeps it with the rest of the registration, so a relaunch shows it before the first verify, and a count an admin changes later arrives with the next verify. A registration made by an earlier build has no count stored and none is guessed: until the first verify after the update brings one, 15 seconds after launch, the window says only what holds for every key (Deregister This Mac takes this Mac off the key). The registered window explains the key by its count:
- One Mac - the key moves. Registering it on another Mac with the same email lets this Mac go, and this copy returns to unregistered at its next verify.
- Several Macs - the key fills up. Each Mac registers with the same email and key, and once the key is full the server refuses another Mac, in words the window shows, until one is deregistered in the registration window on that Mac or released under My Licenses at azcode.dev.
For a key that holds several, the window also shows how many Macs it is in use on, this one included, out of how many it registers ("Macs in use: 2 of 5"). The server returns that count with every registration and verify, and the app keeps it with the registration. Opening the window verifies at once, the way DBClient's License pane does, so a Mac that joined or left the key since the last daily check is counted; offline, the window shows the last count it knew. The line is left out for a one-Mac key, which is only ever in use on the Mac that holds it, and while the server has not said (a server from before the count was sent). The count is cleared when this Mac leaves the key, and a verify answer that lands after this Mac was deregistered changes nothing, so a late "valid" never registers the copy again.
The app states no count of its own: before registering it says nothing about Macs, since an unregistered copy asks the server nothing until a free license is requested. The product site reads the count on sale from the store as its pages load.
To protect battery longevity, the app prevents unnecessary short charge cycles between bounds. When the charge level is between the lower and upper bounds, charging is inhibited by default — including after an app restart or crash. The only ways charging begins are:
- The battery drops below the lower bound (automatic — charges all the way to the upper bound)
- The user toggles Charge to Upper Bound (explicit — charges to the upper bound, then resets)
This ensures charge cycles are always full (lower → upper) rather than fragmented micro-charges.
When the battery is above the upper bound, this toggle appears. When enabled, the app actively discharges the battery down to the upper bound, rather than waiting for passive drain under load.
Note: While discharge is active, system sleep is temporarily disabled (displayed as a warning in the UI). Sleep is restored immediately when discharge stops (either by reaching the target or toggling off). If the app is force-killed or crashes, a watchdog daemon automatically cleans up within a few seconds.
When a discharge stops, the app explicitly re-writes the charging-inhibit key: on some Macs the firmware clears it while discharge is active, and without the re-write charging would silently resume past the upper bound.
When the battery is between the lower and upper bounds and charging is inhibited, this toggle appears. When enabled, the app allows charging until the upper bound is reached, then automatically resets the toggle and re-inhibits charging. Toggling it off mid-charge stops charging immediately and re-inhibits.
A one-shot full charge for days when you need maximum battery (e.g. heading out without a charger). The toggle appears in auto mode whenever a power adapter is connected and the battery is not already full. While active, the effective charge ceiling is 100%; the configured bounds are never modified, and the upper-bound dragger is hidden from the slider (the range highlight extends to 100% instead) since it has no effect until the charge completes. When the battery is full, the toggle clears itself, the dragger returns, and normal auto management resumes with your original bounds.
"Full" means the displayed percentage reaching 100% or the battery's own fully-charged signal, whichever comes first. Worn batteries can terminate their charge below a displayed 100%; the BMS signal completes the one-shot there instead of holding the charge state open forever.
The one-shot is tied to the current AC session:
- Reaching full clears it; charging is inhibited and the battery holds at full while plugged in (no top-up micro-charges).
- Unplugging cancels it. At or above the lower bound, a later reconnect parks at the current level as usual. Below the lower bound, the intent downgrades to Charge to Upper Bound, so a reconnect behaves exactly like the normal below-lower recovery.
- Toggling it off mid-charge re-inhibits immediately and clears a Charge to Upper Bound that had been running underneath it (armed at a plug-in below the lower bound, or by its toggle, before the full charge started); the next cycle restores the default behavior for the current level: a hold between the bounds, a charge to the upper bound below the lower one.
- Activating it turns Discharge to Upper Bound off (the setting itself, not just temporarily): draining the battery right after an explicitly requested full charge is never desirable. Re-enable discharge manually if you still want it afterwards.
Like Charge to Upper Bound, the toggle is persisted: an in-progress full charge resumes across an app restart or crash.
The upper bound is enforced in software: a poll must observe the crossing and write the charging-inhibit key. While the Mac sleeps no polls run, but the SMC keeps charging whenever CHTE allows it — so a charge left running at sleep time would sail past the upper bound (seen in the field as "closed the lid charging to 50%, came back to 65%"). Two mechanisms close the gap:
-
Pre-sleep pause (at or above the lower bound). macOS announces sleep to apps a few seconds before it happens. If a charge is running there, Ampere writes the inhibit inside that grace window and lets the Mac sleep; in-memory state is deliberately untouched, and the wake handler re-asserts "allow" for unpaused states, so the charge resumes on wake and finishes at the upper bound. The announcement cannot be refused, only reacted to — which is why the below-lower case needs the second mechanism.
-
Sleep hold (below the lower bound). A charge that starts below the lower bound keeps the Mac awake until the upper bound is reached (
pmset -a sleep 0 disablesleep 1via the helper — the same override discharge uses, minus the display-sleep part, so the screen still sleeps). Pausing such a charge at sleep would strand the battery below the range all night; charging through sleep would overshoot; holding the Mac awake is the only outcome that ends inside the range. A lid close during the hold is simply absorbed — the sleep never initiates. Should the Mac sleep anyway (the helper could not apply the hold, which is retried at every poll while the status line warns; the hold was waiting for a crash watchdog; or the sleep was forced), the pre-sleep pause applies below the lower bound too: the charge pauses and resumes on wake, so the Mac wakes low rather than charged past the bound. Once the battery climbs past the lower bound, the hold persists only while the lid stays closed (the evidence that a sleep was absorbed); with the lid open it releases, and the pre-sleep pause covers any later sleep attempt. While active it shows the same orange "sleep is disabled" warning as discharge. It is released by reaching the upper bound, unplugging, disabling auto charge, quitting — or, after a crash, by the watchdog through the persistent pmset markers. The hold intent is persisted, so a restart mid-charge (including an in-app upgrade with the lid closed) re-arms it. The hold shares the system-wideSleepDisabledbit with other keep-awake tools (e.g. Lidless), so two protections keep them from trampling each other: the bit's pre-hold value is captured and put back on release — finishing a charge must not cancel the other tool's hold and sleep a lid-closed Mac out from under it — and while the hold is engaged the bit is re-checked every poll and re-applied if the other tool's auto-off timer, quit, or crash watchdog cleared it. A captured "1" is honored only if the bit still reads 1 when the hold releases: a holder that released mid-hold gets sleep restored, never a Mac stuck unable to sleep. -
Charge to Full is exempt. Its ceiling is 100%, so a sleeping Mac cannot overshoot it, and charging through the night is the point of the feature.
Residual gaps, by design: plugging in a Mac that is already asleep charges it with no app awake to manage the bounds; a crash mid-hold restores system defaults (charging allowed, sleep restored); a keep-awake tool that raises the shared SleepDisabled bit while a hold or discharge is already engaged is indistinguishable from our own override (the bit has no owner), so the release still restores the captured pre-override value; and only the charge hold re-verifies the bit — an external clear during an active discharge can still sleep a lid-closed Mac (the wake handler re-asserts the discharge state on wake). All are corrected the next time the app runs a poll — at wake or relaunch — where the standard above-upper handling (inhibit, plus discharge-to-upper if enabled) takes over.
Two things ask for the admin password while the app is running: Revoke in the settings window, and a charge-control action that has to grant access again (after Revoke, after a declined prompt, or when the installed helper has to be replaced). A prompt takes as long as the person takes, and once it is answered its script restores, replaces, or removes the helper on that schedule. Two things follow from that, and both used to be wrong.
- The prompt does not run on the queue the helper's writes go through. There it held up everything that has to land in order behind those writes: the sleep handler waited for it and the Mac slept unprepared, a discharge was not stopped at its target for as long as the prompt stayed open, quitting waited out its six seconds, and the restore a lapsed license calls for waited behind it too. That queue now carries helper calls only.
- Charge control is frozen while a prompt is open. With the prompt's script no longer in line with the helper's writes, a write that landed around it could outlive the access needed to undo it (an inhibit written between Revoke's restore and the removal of the rule, for one). So before the prompt opens, behind any write still in flight: an active discharge is stopped and a sleep hold released (
nodischarge, then a fresh watchdog), and charging is left the way a sleep would leave it, which pauses a charge that is short of its bound and leaves Charge to Full and a manual choice alone. On firmware without CHTE there is nothing to stop; the target is settled as before a sleep. Where this account cannot run the helper (after Revoke, or a declined prompt) nothing is in force and there is nothing to freeze. From then on nothing is written until the prompt is answered: polls stand back, the panel's charge controls and the settings window's Auto Charge switch and Revoke stay where they are but take no input, no second prompt opens behind the first, and a sleep that begins has nothing left to prepare and nothing to wait for.
Once the prompt is answered, charge control goes on as it does after a sleep: the poll re-asserts the state it believes in, restarts a discharge, and arms a sleep hold again where they are still wanted. That holds for a cancelled prompt (a cancelled Revoke is not reported as an error) and for a grant, whose setup restores on its way; only a Revoke that went through has nothing to go on with. A removal that ran and failed stopped at its restore, which may have got part-way: charge control goes on, and the restore joins the cleanup retry, with its warning in the status line until the retry has landed (see Watchdog Daemon). Which of the two a failed prompt was is read from the error number osascript reports (-128 for a cancelled dialog), never from the message, which follows the system language.
The frozen state is in force while the prompt is open, unlike the other holds: quitting restores it, at once, and a license lost meanwhile puts it back. A grant that lands as the Mac goes to sleep is followed by what the sleep handler would have written, since its setup has just restored. The launch prompt, and the one a takeover or a new registration brings, were never on that queue: they come before the instance has anything in force, and the cleanup that follows them starts from whatever they left.
When auto charge is off and a power adapter is connected, a manual Pause Charging / Resume Charging button is available.
The Keep Awake row on the panel stops the Mac from going to idle sleep while a power adapter is connected, for a chosen duration (15 minutes to 8 hours, or Forever). While a timed session runs, the row shows its end time ("until 3:45 PM"). It holds a standard macOS power assertion, the same mechanism caffeinate uses, so it needs no admin rights and cannot outlive the app: quitting releases it, and the kernel drops it automatically after a crash. The display still sleeps normally unless the display option below is on. Keep Awake is a paid feature: on a free license, or with no license, the row shows a lock and an Unlock… button, which opens the registration window, in place of its controls, no session can start, and a session that is running when the paid license lapses ends at once, the way unplugging ends it. A paid copy's session survives an update and a restart as before; a copy that no longer holds a paid license does not resume one.
Keep Display On, a button with a display symbol beside the duration menu, is an option of the running session: it can only be turned on while Keep Awake is on and a power adapter is connected, and it is disabled otherwise. With it on, the session holds the display-sleep assertion instead (what caffeinate -d holds; it implies the system stays awake too), so the display stays on and the Mac does not lock on its own while the session runs. It is off by default, and turning it on shows a warning first: anyone at the Mac can use it until it is locked or the session ends; a screen saver that is set to start may still start and lock the screen; a closed lid, a hot corner, a manual lock, and a lock managed by an organization all work as before. Because it changes who can use the Mac, turning it on then asks for Touch ID, or your account password where no Touch ID sensor is reachable (a Mac without one, or a MacBook closed in clamshell mode); the prompt is the system's, Ampere stores nothing from it, and cancelling it or a prompt that fails leaves the option off. Turning it off asks nothing, and a restart mid-session resumes the option without asking again. Whatever ends the session (turning Keep Awake off, the deadline, unplugging) turns the option off with it, so it is never on without a session, at rest or after a restart. Switching the option while a session runs swaps the held assertion, so the process holds exactly one at any time. No lock setting is ever changed, and the assertion cannot outlive the app.
A session is AC-only. Both switches are disabled on battery, and unplugging the adapter ends a running session: the toggle and the display option go off, and plugging back in starts nothing until you turn Keep Awake on again. A poll that cannot read the battery at all releases the assertion for that tick but does not end the session; only a Mac known to be on battery does. The duration is a wall-clock deadline ("until 3:45 PM"), not a stopwatch: it survives an app restart mid-session, and when it passes the toggle turns itself off. Changing the duration during a session restarts the countdown from now.
A running session shows in the menu bar, to the left of the battery. The symbol is a cup while only the Mac is kept awake. While Keep Display On is on it is a badge, a white display on the accent color, the way the Keep Display On button on the panel looks when it is on: the one state the menu bar item draws the eye to, because the Mac does not lock on its own while it lasts. A timed session shows the time it has left beside the symbol, in whole minutes rounded up ("1h 45m", "45m", and "1m" for the last minute), redrawn once a minute; a Forever session shows the symbol alone. Settings → Keep Awake Time in Menu Bar (on by default, offered with a paid license) hides the time and keeps the symbol, for a narrower menu bar item. Hovering the item says when the session ends and what the display does ("Keep Awake until 3:45 PM. The display is kept on, so the Mac does not lock on its own."). The battery and the percent do not move when a session starts or ends, and neither does the panel when a session is started from it (see Menu Bar Item and the Attached Panel). Whatever ends the session takes the symbol away with it, so a session that ended because the adapter was unplugged no longer ends unseen.
Unlike the charge sleep hold and the discharge override (which use the system-wide pmset override precisely because they must survive a lid close), Keep Awake never blocks lid-close sleep on an undocked Mac. In clamshell mode (external display + power) a closed lid does not sleep the Mac anyway.
Six of the twelve cards on the panel have a second unit, and clicking one switches it. Hovering such a card shows a swap glyph, and its tooltip says what a click switches to.
| Card | Starts as | A click switches to |
|---|---|---|
| Battery Served | years and months ("1y 8m") | days ("608d") |
| Temperature | the unit macOS is set to | the other of °C and °F |
| Health | percent | full-charge over design capacity, in mAh |
| Raw Charge | percent | current charge over full-charge capacity, in mAh |
| Adapter Current, Battery Current | amps | milliamps (the two switch together) |
Each choice is saved the moment the card is clicked and comes back after a restart, an update, or a crash. Temperature is the one card with no unit of its own to start in: until it is clicked it shows the unit set under System Settings > General > Language & Region > Temperature (the region's own unit where that was never changed), so a new install reads Celsius on a Mac set to Celsius. The first click stores the unit it switches to, and from then on the card keeps that choice whatever macOS is set to.
The Checked at time of the last health check, in the About panel, is written the way the same settings say: the Mac's 12 or 24 hour clock, and its region's order of day and month.
Settings… in the panel footer opens the settings in a window of their own, and so does ⌘, while one of Ampere's windows has the keyboard. They used to unfold as rows under the footer, where every new one made the panel taller. The window groups them by subject, with a line under each on what it does:
| Section | Settings |
|---|---|
| Charging | Auto Charge, the switch between auto and manual mode (see Auto Charge) |
| General | Launch at Login |
| Menu Bar | Percent in Menu Bar, and with a paid license Keep Awake Time in Menu Bar (see Keep Awake) |
| License | whose license this copy runs on; Manage… opens the registration window |
| Advanced | Admin Access with its Revoke button (see Uninstall), shown while this account holds the access |
Every switch acts at once; there is nothing to apply or save. The window is as tall as its rows, which come and go with the license and with admin access, and its top edge stays where it is as they do. On a screen with no room for all the rows it takes the height there is and scrolls. The first time, it opens centered on the display the panel is on. After that it reopens where it was last left, in the same run and after a relaunch or a crash: the place is saved as the window moves. It is moved up if it would now run off the bottom of its screen, and centered again if the display it was left on is no longer connected (no display shows enough of its title bar to move it by).
An attached panel that is not pinned closes when the window opens, as it would at the next click outside it. A pinned panel stays open beside the window, and so does the panel's own window (see The Panel as a Window); either follows each switch as it is flipped: turning Auto Charge off in the settings window puts the Pause Charging button on the panel at once. The registration window, which Manage… opens, follows the same rule. It used to close the panel whatever its state, so Manage… took a pinned or torn-off panel away with it.
Where the two overlap, the window opens in front of the panel, and after that whichever of them was clicked last is in front. For the attached panel that takes a rule of its own, because macOS draws it on the menu bar's layer, above every ordinary window: opened as an ordinary window, the settings window came up behind a pinned panel and no click could bring it forward. So for as long as an attached panel stays on screen (pinned, or held open by a sheet such as About), the settings window and the registration window are on the panel's layer, which also keeps them above other apps' windows the way the panel is. A window that is already open when the panel is pinned joins the layer behind the panel, not in front of it. Once the panel closes, is unpinned, or is torn off they are ordinary windows again, in the order they were in. The panel's own window is an ordinary window to begin with, so none of this applies to it.
The panel's status line is out of view from this window, so what it would say about charge control leads the window instead: why charge control is on hold (another account's copy has it, an admin password prompt of Ampere's is open, this Mac has no mechanism to hold a charge), or the last thing that went wrong (a password prompt declined after turning Auto Charge on, a Revoke that could not finish). Auto Charge takes no input while such a hold lasts, and neither it nor Revoke does while a password prompt is open (see Password Prompts).
Launch at Login is macOS's to keep, so the switch shows what macOS says: read when the window opens and again each time Ampere becomes active, which is how a login item removed under System Settings > General > Login Items & Extensions comes to show as off. A change macOS refuses puts the switch back and says why in the row.
A copy with no license has no settings: it is held at the registration window (see Charge Bounds and Registration), ⌘, brings that window forward, and a settings window that is open when a registration lapses closes. ⌘W closes whichever of Ampere's windows has the keyboard: the settings window, the panel, or the registration window once a license is registered.
The panel hangs from the menu bar item, and it can be dragged off it. What comes off is a window like any other: a title bar that names the app and its version, a close and a minimize button, and a place among the other windows instead of above them all; it moves by its title bar. While that window is open Ampere is a regular app: it has a Dock icon, it is in ⌘-Tab, and while one of its windows has the keyboard the menu bar at the top of the screen is Ampere's own.
| Menu | Commands |
|---|---|
| Ampere | About Ampere, Settings… (⌘,), Services, Hide Ampere (⌘H), Hide Others, Show All, Quit Ampere (⌘Q) |
| File | Close Window (⌘W) |
| Edit | Undo, Redo, Cut, Copy, Paste, Delete, Select All |
| Window | Minimize (⌘M), Bring All to Front, and the open windows |
| Help | Ampere Help (the How Ampere Works page), Ampere Website, Changelog, Support |
About Ampere opens the About sheet the panel's footer opens. The shortcuts work at all times, with the attached panel too; the menus themselves show only while the panel is a window, because macOS shows no menus for a menu bar app.
The window holds what the attached panel holds, without its first row: the title bar says the name, and a window has nothing to pin. A click on the menu bar item brings the window forward, from under other windows, from another Space, or out of the Dock, and does not open a second panel beside it; a click on the Dock icon does the same. Closing the window, by its close button or ⌘W, makes Ampere a menu bar app again: the Dock icon and the menus go, and the next click on the menu bar item opens the attached panel. A settings or registration window that is open at that moment stays open and keeps the keyboard.
The window is part of what a restart brings back. Open when Ampere quits, is updated, or crashes, it is open again at the next launch as it was left: where it was (by its top-left corner, since its height follows the panel's rows, moved up if it would now run off the bottom of its screen, and centered if the display it was on is gone), and in the Dock if it was minimized. It comes back without taking the keyboard, so a launch at login or the relaunch after an update does not interrupt what you are doing; the first click on the window makes Ampere the active app. Closed, it stays closed. A copy whose license has lapsed has no panel: the window closes with the rest (see Charge Bounds and Registration) and no launch reopens it.
The window is as tall as the panel's rows, which come and go with the power adapter, the mode and the license, and its top edge stays where it is as they do. On a screen with no room for all of them it takes the height there is and scrolls: with every row showing, the panel and its title bar are 874 points tall, more than a 13 inch MacBook has between its menu bar and a Dock at the bottom.
While the window is minimized, covered by other windows, on another Space, or hidden with the app, Ampere polls at its slow rate (see Polling and Health Check Timing).
Two things a drag does not do. With a sheet over the attached panel (About, the Keep Display On warning) the panel does not tear off; close the sheet first. And a pinned panel that does not have the keyboard, because the settings window was clicked last, takes the first drag as the click that gives it the keyboard (measured on macOS 27): the second drag tears it off.
| Scenario | Sleep → Wake | Quit → Restart |
|---|---|---|
| Charge to Upper Bound is ON (charging in progress between bounds) | The charge pauses just before sleep and resumes on wake. The sleep announcement handler writes CHTE=inhibit (in-memory state untouched); on wake the handler re-asserts CHTE per the current state — "allow" here, since the state still says an unpaused charge is running — and the charge finishes at the upper bound. A charge that began below the lower bound doesn't sleep at all: the sleep hold keeps the Mac awake until the upper bound (see Sleep and Mid-Charge Protection); if the Mac sleeps anyway (a hold the helper could not apply, or a forced sleep), the charge pauses the same way and resumes on wake. Toggle stays ON until the upper bound is reached. | Charging resumes automatically. The "Charge to Upper Bound" toggle is persisted across restart so an in-progress charge resumes rather than parking at the current level. On launch the app sees chargeToUpperBound = true and leaves CHTE in the "allow" state; charging continues until the upper bound is reached, at which point the toggle clears itself. |
| Charge to Full is ON (one-shot full charge in progress) | Charging continues through sleep — the ceiling is 100%, so there is nothing to overshoot, and the pre-sleep pause deliberately skips this state. The wake handler re-runs the state machine, which keeps CHTE in "allow" until the battery is full. Toggle stays ON until full. | Charging resumes automatically. The toggle is persisted; on launch the app skips the between-bounds inhibit and leaves CHTE in "allow", so the full charge continues (even past the configured upper bound) until full, where the toggle clears itself. A launch that finds the flag set but the Mac on battery clears it, because the one-shot is tied to the AC session it was started in. |
| Discharge to Upper Bound is ON (discharging above upper bound) | Discharging continues. System sleep is prevented during discharge, so normal sleep should not occur. If forced (e.g. lid close), the wake handler re-asserts the discharge SMC state. Toggle stays ON. | Discharging resumes automatically. The "Discharge to Upper Bound" toggle is persisted. On restart, the app clears stale SMC state, then the first refresh cycle detects the battery is still above the upper bound and restarts discharge. Toggle stays ON. |
On firmware without CHTE all three rows collapse into one behavior: the macOS charge limit holds the target on its own through sleep and across a restart, and the first poll after a relaunch simply hands it the current target again. See Firmware without CHTE below.
- Settings persist across restarts - auto charge, discharge toggle, charge bounds (a free license always relaunches with the default 40 to 60%), keep awake (including a mid-session deadline; not resumed by a copy that no longer holds a paid license), the two menu bar switches (Percent in Menu Bar, Keep Awake Time in Menu Bar), the unit each card was switched to (see Card Units), where the settings window was left (see Settings Window), and the panel's own window, open or not, where, and whether it was minimized (see The Panel as a Window), are saved and restored when the app relaunches. The registration, free or paid, persists too; an unregistered copy relaunches at its registration window with its settings intact.
- Quitting the app restores system defaults - all SMC overrides (charging inhibit, discharge) and power management changes (sleep settings) are cleared when the app exits, and on firmware without CHTE the macOS charge limit is put back to whatever it was before. Your Mac returns to its normal charging and sleep behavior. If the app crashes or is force-killed, a watchdog daemon cleans up automatically within a few seconds. If the Mac was shut down mid-override instead, the next launch restores it; should that restore fail (pmset not answering right at login, say), the status line says so and the app retries every two minutes until it succeeds.
The app periodically verifies that the actual SMC key values (CHTE and CHIE) match the expected state. A CHTE mismatch is repaired, not just reported: firmware or a USB-C PD renegotiation can silently reset the key (observed across sleep/wake), and the state machine is edge-triggered — it never re-issues a write for a state it believes is already in force, so a drifted key would otherwise stay drifted until the next sleep/wake while the battery charges past the bound (or refuses to finish a charge). The health check re-writes the expected value and re-verifies on the next cycle. The first repair attempt is silent; only a mismatch that survives a repair shows the warning in the popover and turns the menu bar battery icon orange — at that point the helper itself is suspect, and the warning's advice (revoke & re-grant admin) is appropriate. CHIE mismatches are reported but never auto-repaired: starting or stopping a discharge belongs to the state machine, with its sleep override and watchdog attached.
Health checks only run while a power adapter is connected — on battery the app is not managing charging, so there is no expected SMC state to verify. Until the first check of a session has run, the About panel shows the check as waiting for power adapter (on battery) or pending (plugged in, during the warm-up below).
On firmware without CHTE (see Firmware without CHTE below) the check compares the target powerd is enforcing (pmset -g battlimit) with the one the app last handed to the macOS charge limit, plus CHIE, which must be clear since nothing writes it in that mode. The agent applies a new target at its next once-a-minute evaluation (82 seconds observed on macOS 27.0), so a mismatch inside a 150-second settle window after a write is not reported; past it the target is re-issued, silently the first time, and only a mismatch that survives that shows the warning. The About panel names the mechanism in force. While macOS's own calibration charge runs (see Firmware without CHTE below) the check reports suspended, with the registered limit marked (ignored by macOS), repairs nothing, and resumes the comparison when the override clears, which happens by powerd's clock about 12 hours after the charge began, not when the battery fills.
The app polls battery state on a timer. Power-source changes (plug/unplug, charge-level ticks) also trigger an immediate poll via an IOKit notification, so adapter transitions are handled within about a second rather than at the next interval — a short unplug between polls still cancels Charge to Full and stops an active discharge. Health checks run every poll cycle after an initial 3-cycle warm-up (to let launch cleanup settle), whenever a power adapter is connected.
| Panel out of view (slow) | Panel in view (fast) | |
|---|---|---|
| First poll | Immediately on launch | Immediately as it comes into view |
| Poll interval | 60s | 10s |
| First health check | Cycle 4 — 3 min after launch | Cycle 4 — ~30s after open* |
| Health check interval | Every cycle — 60s | Every cycle — 10s |
* The cycle counter is global and does not reset when switching between fast and slow polling. If the app has already been running, the first health check after opening the panel depends on the current cycle count.
The panel is in view while it hangs from the menu bar item, and, once it is a window, while macOS reports any part of that window as showing. A window that is minimized, covered by other windows, on another Space, or hidden with the app is out of view: polling drops back to 60s, and returns to 10s, with a poll at once, the moment the window shows again.
A health check also runs right after admin access is re-granted from inside the app (when enabling a charge-control feature reinstalls the helper), so the warning clears (or appears) without waiting for the next scheduled check. It runs after the poll that follows the grant, not before it: the setup's restore leaves charging allowed, and a check run first took what the state machine was about to write for a mismatch, repaired it itself, and left the panel a poll behind. A check can repair, and the password prompt takes as long as the person takes, so that check runs only where a scheduled one would: this copy still holds charge control (a registration that lapsed while the prompt was up has put it on hold, and a repair written there would come after the hold's restore, with nothing left to put it back at quit), the Mac is not on its way to sleep (a repair would undo the pre-sleep pause written a moment earlier), no helper call is in flight (the state machine's own write, say, which the poll after it checks), and a power adapter is connected. Otherwise the next scheduled check stands in. Revoking runs no check; it clears the warning, since the access a repair would need is gone. After an app relaunch — including the revoke → relaunch → re-grant flow — the first check follows the normal warm-up schedule above.
Every line the app, the helper, and the watchdog log goes to the unified log under the subsystem com.az-code-lab.ampere (categories app and helper), with the message marked public:
log show --last 1h --predicate 'subsystem == "com.az-code-lab.ampere"'
NSLog is not used anymore: from macOS 27 its messages show up in log show only as <private>, which made the app's own diagnostics unreadable exactly when they were needed. The watchdog logs one line when a restore starts failing and one when it succeeds, so a crash whose cleanup never completes is visible there too.
The app checks the Homebrew cask for a newer version 5 minutes after launch and about once a day after that. When one is found, the menu bar battery icon gains a small blue badge dot (hover for the version; the dot renders alongside the orange health-warning tint when both apply) and the panel footer shows an Update to X button. Clicking it:
- Downloads the release DMG from GitHub Releases (progress shown in the footer, with a cancel button).
- Verifies the download: SHA-256 must match the cask, the code signature must be intact, the Team ID must match the running app, and the macOS the new bundle asks for (
LSMinimumSystemVersion) must not be newer than the one this Mac runs. - Swaps the new bundle into place (one atomic exchange; volumes without swap support fall back to two renames) and relaunches.
The relaunch takes the normal quit → restart path: SMC overrides are restored on the way down, and persisted state (auto charge, bounds, an in-progress charge/discharge to upper bound) resumes in the new copy. If the bundled SMCWriter changed, the next launch asks for your admin password once to install the new helper — same as after a Homebrew upgrade.
If any step fails (e.g. the install location isn't writable), the error is shown next to the button and nothing is changed; brew upgrade --cask ampere always works as a fallback. Updating in-app leaves Homebrew's recorded version behind until the next brew upgrade, which harmlessly reinstalls the current release.
A release is offered only to a Mac that can run it. The cask's depends_on macos: line names the oldest macOS a release supports (Homebrew reads a bare release name such as :tahoe as "this or later"). When this Mac runs something older, no update is offered and the installed version stays; a clicked Check for Updates answers Needs macOS N instead of Up to Date. brew upgrade refuses the same release from the same line, so both channels agree. A release name newer than the running build knows is not treated as a refusal (it may be the very macOS the build runs on), which is why step 2 checks the downloaded bundle as well: that check needs no name table, and it is the one that keeps a working copy from being replaced by an app macOS will not open.
The launch floor (LSMinimumSystemVersion and the deployment target in Package.swift) is 15.0, the same as the supported floor above and as the cask's depends_on macos: :sequoia. Through 0.0.65 it was 14.0: versions up to 0.0.64 install whatever the cask advertises without asking whether it can open here, so the floor stayed low while the macOS version registered copies report (see Charge Bounds and Registration) still showed Macs on macOS 14. Unregistered copies report nothing, so one of 0.0.64 or earlier on macOS 14 can still swap in a release that will not open there.
./run.shOr manually:
swift build -c debug
.build/debug/Ampererun.sh and release.sh pass the linker the SDK explicitly (SDK_FLAGS in both scripts). Under Xcode 27's toolchain a bare swift build produces a binary stamped as built against the SDK of its deployment target: SwiftPM's Swift Build engine runs swiftc without SDKROOT, and clang then records the deployment target instead of the SDK version. AppKit and SwiftUI run such a binary in that older release's compatibility mode on every later macOS; with the macOS 14 target of the time, macOS 27 showed an empty "Ampere Settings" window at launch. Check a build with otool -l .build/debug/Ampere | grep -A4 LC_BUILD_VERSION; the sdk line must show the SDK you built with (27.0 under Xcode 27), not the deployment target's 15.0.
Both scripts also pass their build output through build_progress (build-progress.sh). The Swift Build engine's progress lines ([108 / 109] Ampere-product) are not done over total: they count the tasks started over the tasks that may still run, the engine sends at most one every 100 ms, and it never sends the final state again. A build whose last steps finish inside that window therefore ends on a count short of its own total, with Build complete! under it (ten identical rebuilds ended on 37 / 38 nine times and on 38 / 38 once). The filter draws the progress lines in place while the build runs and clears them when it ends, so what remains is SwiftPM's verdict and its diagnostics; where the output is not a terminal the progress lines are left out. release.sh builds the tests through it and then runs them with swift test --skip-build, so no test output passes through the filter.
Delete Ampere.app from Applications, or:
brew uninstall ampereQuit Ampere first if it is running (Finder refuses to trash a running app; Homebrew quits it). Quitting restores charging and sleep settings. Two minutes after the bundle is gone, the cleanup job removes everything else, so the Mac ends up as if Ampere had never been installed:
/Library/PrivilegedHelperTools/az-ampere-smc- the SMCWriter helper binary (runs as root to write SMC keys)/etc/sudoers.d/az-ampere- the sudoers rule that allows passwordless execution of the helper/Library/Application Support/az-ampere/- state directory for the saved-sleep markers (only exists if discharge or the mid-charge sleep hold was ever used)/Library/LaunchDaemons/com.az-code-lab.ampere.cleanup.plist- the cleanup job itself~/Library/Preferences/com.az-code-lab.ampere.plist,~/Library/Caches/com.az-code-lab.ampere,~/Library/HTTPStorages/com.az-code-lab.ampere, and~/Library/Saved Application State/com.az-code-lab.ampere.savedState- preferences (including the registration), the update check's cache, and window state, for every account on the Mac
A copy deleted while it was running (rm -rf, or an uninstaller that does not quit it first) is waited for: the job removes everything two minutes after that copy quits. The job exists once the app has run from that location with admin access granted, and only runs while it is allowed under System Settings > General > Login Items & Extensions. If a restore fails, it keeps everything in place for the watchdog to retry and tries again at the next boot. There is no zap stanza; brew uninstall ampere alone is the complete removal. Two things stay: the copy of Ampere.app in the Trash until you empty it, and the Open at Login entry if you had enabled it, which macOS manages. Switch launch at login off in Settings before uninstalling, or remove the entry under Login Items & Extensions.
Quit Ampere first. The helper restores charging and sleep settings, then removes every file above and unloads the job; nothing is removed if the restore fails.
sudo /Library/PrivilegedHelperTools/az-ampere-smc purgeClick Settings… in the panel footer, then Revoke on the Admin Access row of the settings window. This restores charging and sleep settings, then removes your account's sudoers line and, once no other account is authorized, the helper binary, the state directory, and the cleanup job (one administrator prompt). Preferences stay, since the app does. Charge control is frozen while that prompt is open (see Password Prompts): cancelling it changes nothing and charge control goes on. If restoration fails, the files and recovery watchdog remain available, charge control goes on, and the app reports the failure with the cleanup warning until its retry has finished the restore. sudo /Library/PrivilegedHelperTools/az-ampere-smc uninstall does the same for every account at once and also keeps preferences.
"Pause Charging" does nothing / no password prompt appears
The helper binary may be corrupted. Fix by revoking and re-granting access:
- Click Settings… in the panel footer, then Revoke on the Admin Access row of the settings window
- Relaunch the app - it will prompt for your password and install a fresh helper
This section documents the implementation details of SMC-based charge control and discharge, including the problems encountered and their solutions.
| Key | Type | Description |
|---|---|---|
CHTE |
ui32 (4 bytes) |
Charge terminate / inhibit. 0x01 00 00 00 paused, 0x00 00 00 00 allowed. |
CHIE |
hex_ (1 byte) |
Charge inhibit enable / discharge. 0x08 discharge, 0x00 normal. |
| Pause button | Expected CHTE | Expected CHIE |
|---|---|---|
| Paused | 0x01 00 00 00 |
0x00 |
| Resumed | 0x00 00 00 00 |
0x00 |
| Charge level | Expected CHTE | Expected CHIE |
|---|---|---|
| >= upper bound | 0x01 00 00 00 |
0x00 |
| >= lower bound and < upper bound | 0x00 00 00 00 or 0x01 00 00 00 |
0x00 |
| < lower bound | 0x00 00 00 00 |
0x00 |
While Charge to Full is active, this table applies with the upper bound read as 100 and CHTE expected to be 0x00 00 00 00 (allow) everywhere below it. (Discharge is always off in that state — activating the one-shot disables it.) For any 100% target, the battery's FullyCharged flag counts as "at the bound", covering worn batteries that terminate below a displayed 100%.
| Charge level | Expected CHTE | Expected CHIE |
|---|---|---|
| > upper bound | 0x01 00 00 00 |
0x08 |
| >= lower bound and <= upper bound | 0x00 00 00 00 or 0x01 00 00 00 |
0x00 |
| < lower bound | 0x00 00 00 00 |
0x00 |
Both keys are written via IOKit's IOConnectCallStructMethod (selector 2) to the AppleSMCKeysEndpoint service (falling back to AppleSMC). Writing requires root privileges. Reading does not require root.
The firmware that ships with macOS 27, and with the macOS 26.7 update, no longer has a CHTE key: the SMC reports it as not found, and every helper write of inhibit or allow fails. Apple's replacement, a firmware charge-limit interface (bfD0/bfE0/bfF0), exists in the key table but refuses every call from a process without the private com.apple.private.iokit.soc-limit entitlement, root included. CHIE still works. Without the inhibit key the previous design could not hold a level at all: a discharge that reached the upper bound resumed charging at full current within seconds, and the health check never ran because its first read failed.
On such firmware the app takes a different path, decided when it takes charge control from what is present rather than from the macOS version (the decision is spelled out at the end of this section): it holds the battery through macOS's own Manual Charge Limit, the feature behind System Settings > Battery > Charge Limit. PowerUIAgent (root) keeps that feature's switch and target in its preference domain, com.apple.smartcharging.topoffprotection under /var/root/Library/Preferences, as MCLFeatureState (1 = on) and mclLimitValue (percent). The agent registers the target with powerd and the firmware enforces it: charging stops at the target, including during sleep and across a reboot, and a battery above the target is drained down to it by the firmware itself (at about 2 A; the firmware decides when to begin, observed anywhere from one to eight minutes after the target was set). The agent's own request interface refuses targets below the range its slider offers, so the helper writes the two keys directly (native-limit:<percent>, valid 1 to 100) and posts the Darwin notification com.apple.smartcharging.defaultschanged, which the agent reloads its settings on. The agent applies a new target at its next once-a-minute evaluation (56 and 82 seconds observed). Nothing is written to CHTE or CHIE in this mode, and no pmset override is needed, because the firmware, not a poll, does the enforcing.
The app maps its existing state machine onto one number. The machine still decides the intents exactly as before (rules 1 to 3, the charge-to-full session, the unplug edge); what changes is what each outcome writes:
| State machine outcome | Target handed to macOS |
|---|---|
| Charge to Full | 100 |
| Charge to Upper Bound (explicit, or rule 1 below the lower bound) | the upper bound |
| Above the upper bound with Discharge to Upper Bound on | the upper bound (the firmware drains to it) |
| Any other paused state (between bounds, at the bound, above it with discharge off) | the current level (a hold) |
| Manual mode, paused on AC | the current level |
| Manual mode, resumed | released: the user's own setting is back |
A hold follows the level up while the agent settles: the agent needs up to a minute to apply a target, so a percentage that ticks up meanwhile becomes the new target rather than being drained back to the old one (the firmware drains a battery that sits above its limit). The chase ends by itself, since charging stops the moment the limit lands, so a fresh hold ends a percent or two above where it began and stays there. A dip under load on AC is not followed either: the firmware leaves a dip of up to 5 points alone and charges a deeper one back to within a few points of the limit (Apple documents that charging resumes once the level drops more than 5% while connected to power). The displayed level can also sit at the limit for hours and then step down several points inside a minute: the gauge latches the reported level at the limit, which is registered as end of charge (chargeSocLimitIsEOC in pmset -g battlimit), while the battery actually drifts a few points down, and the display catches up when the latch releases (60% to 56% at one point per 20 seconds, observed on macOS 27.0). Neither is a hold failure, and the hold does not top the battery up; Ampere charges again below the lower bound or on request. Off AC the intent is written ahead of the next plug-in: an armed charge starts the moment the adapter connects, and a hold follows the falling level down so a reconnect never charges toward a stale level. Reaching a bound turns the charge target into a hold at the same number without another write. Sleep holds and the pre-sleep pause do not arm in this mode, and the wake handler re-asserts nothing. The sleep announcement handler does one thing: it waits for a helper call still in flight and settles the target against the current intent. That call's completion would otherwise record its target only after wake, while polling is blocked, so a full charge cancelled during the call would ride through sleep at 100%. Which call it was does not matter. A target write is recorded first. A cleanup retry leaves nothing to record, and the settling write does not wait for it: the retry's completion, which is what frees the poll to write again, cannot run before the handler returns, so a full charge cancelled while a retry was in the helper used to stay at 100% until wake. The same settling freezes the target ahead of one of Ampere's own password prompts, and follows a helper install that lands on the way into sleep: its setup's restore released the target, which would otherwise pass for current and let the Mac sleep with no limit at all (see Password Prompts).
macOS's calibration charge. Every few weeks while a charge limit is in use, macOS charges the battery to 100% once, to keep the gauge's state-of-charge estimate accurate. Apple documents this for the Charge Limit feature, and on this firmware that feature is what Ampere holds with, so the hold cannot prevent it. powerd's battery-gauging policy decides it at a check it runs at most once every 12 hours, at the first of its hourly alarms that falls 12 hours or more after the previous check (the alarms in between log Not enough time has passed since last charge to full check: <date>), and asks for the charge when the last full charge is more than 21 days old (Last full charge date was 21.4 days ago, try and charge to full; both are constants in powerd on macOS 27.0.1, 43200 and 1814400 seconds). It then posts the Darwin notification com.apple.system.powersources.chargingtofulloverride with its state set to 1 and suspends its limit policy (SOC limit policy suspend due to mitigation active:1); PowerUIAgent keeps registering every target it is handed and logs Battery mitigations are in place, MCL will be ignored. The override is lifted by the clock, not by the battery: powerd records the full charge at the first hourly alarm that sees it (FC detected, updating lastFullyCharge date to <date>) but re-decides only at its next check, so the state stays at 1 until about 12 hours after the charge began, later if the Mac sleeps through that alarm, whatever the battery did meanwhile. The request is saved to disk and re-applied at boot (HandleBatteryDataUpdate Boot ChargeToFull <state>), so a restart does not end it, and neither does unplugging. By powerd's code, a charge that has not reached full by that check is written off as done there and the override kept until the check after it, about 24 hours in; this case has not been observed. pmset -g battlimit lists the target as registered with no sign of the suspension, which is why the health check used to pass on it while the status line said holding and the ETA counted down to the upper bound. The app reads the notification's state at every native-mode poll (it is public, needs no privileges, and reads 0 until powerd first posts it after a boot) and, while it is set: the status line says Auto: overridden — macOS is charging to full to calibrate the battery (Pause overridden — ... for a manual pause), in orange, and once the battery reports full (fullyCharged, or 100%) Auto: overridden — calibration charge done, macOS lifts the override within about 12 hours; the ETA aims at full; the About panel explains the charge, and then the wait, under the mechanism line; and the health check reports suspended with the registered limit marked (ignored by macOS) rather than a pass, repairing nothing, full battery or not. A Charge to Full is not reported as overridden, since it was going to 100% anyway. The state machine runs unchanged, so the hold keeps following the level up, one write per percent, and the limit is at the level the battery has reached whenever the override clears: the hold resumes right there, normally at 100%, exactly as after a Charge to Full, and Discharge to Upper Bound brings the battery back to the bound. The edges are logged with the level (macOS is charging to full to calibrate the battery (charge-to-full override at 47%), macOS calibration charge reached full at 100%; macOS lifts its override at its next policy check, about 12 hours after the charge began, macOS calibration charge ended at 100%). Observed on macOS 27.0.1: the override began at 23:49:30 on 2026-10-05 at 47%, the last full charge 21 days earlier; the hold followed the level to 100%, reached before 01:00; powerd recorded the full charge at its 01:49 alarm and kept the override, the battery full and resting on AC, pending the check due at 11:49. Whether the calibration charge also overrides CHTE on firmware that has it is not known; the override is watched only in native mode, where the limit is the hold.
Before the first override the helper saves the agent's original switch and target to /Library/Application Support/az-ampere/saved-native-limit ("<state> <limit>", - for an absent key). Every restore path, restore at quit, the launch cleanup, the crash watchdog, uninstall, and the cleanup job, runs native-limit-release: it asks the agent to switch the feature off through its own client interface (the private PowerUI framework, resolved at runtime), which is the only path on which the agent clears the limit it registered with powerd; a preference write turning the feature off leaves that registration in place. If the user had a limit of their own, it is switched back on with their value. The marker is consumed only after every step succeeds, so a later restore can retry with the same originals. nodischarge does not release the limit; it only ends a discharge. A change the user makes in System Settings while the app is managing is overwritten by the app's next target, and the pre-session value is what gets restored.
The restore paths also treat a missing CHTE as nothing to restore. Without that, restore failed at the allow write on this firmware and the watchdog it was meant to retire retried every two seconds for as long as the Mac stayed up. Only the SMC's own not-found status (0x84) counts as missing: the write is attempted first, and an SMC that fails to answer (a bus collision, a timeout) leaves that failure standing, so a restore never reports success with charging still inhibited and retires the watchdog on the strength of it.
Which mechanism runs is decided when the app takes charge control, from what is present rather than from the macOS version, in this order: the CHTE key wherever the SMC has it (on macOS 26.4 to 26.6 both mechanisms exist, and CHTE still wins, because it is immediate and exact); otherwise the macOS charge limit, but only when the private client class behind System Settings' Charge Limit exists and answers the manual-limit calls the release path makes, and pmset -g battlimit answers, which the health check verifies against. Both checks are class inspection and a read, need no admin rights, and are skipped entirely on a Mac with CHTE. An SMC that does not answer the CHTE probe at all decides nothing: the probe is repeated a few times, and if it stays unanswered charge control goes on hold (the status line says so, the controls are hidden, nothing is written and no password is asked) and the app asks again at every poll, so one failed read at launch cannot run a CHTE Mac on the macOS charge limit for the whole session. A Mac with neither, firmware that lost CHTE under a macOS that predates the charge limit (macOS 15 with the firmware its later security updates install), gets no charge control rather than a target nothing enforces: a preference write there would report success, the health check could never read a limit back, and the release the helper would later need would have no client to talk to. On such a Mac the app monitors only: no helper prompt, no cleanup writes, no watchdog, nothing to restore at quit, the controls are hidden, and the status line and the About panel say why. That verdict is not final either: the probes run again at every poll, so a pmset -g battlimit that could not be run at launch does not decide the session (a Mac with neither mechanism pays one SMC probe and a class lookup per poll; pmset is only run where the class exists). A helper an earlier version installed is left alone and can still be revoked.
Everything above is bypassed while CHTE exists: on that firmware the helper, the state machine, the sleep handling, and the health check run exactly as they always did.
macOS 27 reorganized the battery's registry data. The AppleSmartBattery entry lost its top-level DesignCapacity, AppleRawMaxCapacity, AppleRawCurrentCapacity, and Temperature keys, and its BatteryData dictionary shrank to eleven keys. The detailed BatteryData, under the same key names as before and including LifetimeData, now sits on a child entry of class AppleSmartBatteryPack. (ioreg -a silently omits that dictionary, because it holds a value a property list cannot carry, which makes the data look deleted; ioreg -l shows it.)
The reduced BatteryData that stayed on the battery entry carries the same capacities as DesignCapacity, FullChargeCapacity, and RemainingCapacity (equal to the pack's raw values when compared), and the SMC's TB0T sensor tracks the gauge temperature to 0.1°C, so Health, Raw Charge, and Temperature read those when the top-level keys are absent. Battery Served is computed from the gas gauge's operating-hours counter, LifetimeData.TotalOperatingTime: the gauge runs off the cells and has counted since the pack was built, so the counter is the battery's age. The app looks for LifetimeData on the battery entry first and then on its AppleSmartBatteryPack child. On a 2021 MacBook Pro the counter reads 44,063 hours, which dates the pack within two weeks of the manufacture week encoded in the battery's serial number.
Through 0.0.72 a panel dragged off the menu bar item stayed the popover's own window, which AppKit moves by its background. On macOS 27 SwiftUI content no longer counts as background for that purpose: a mouse-down anywhere the hosting view draws (the panel's background fill, text, the cards) does not start a window drag, and the panel is SwiftUI edge to edge, so a torn-off panel could not be moved at all. From 0.0.64 the panel carried a SwiftUI WindowDragGesture for that state. The torn-off panel is an ordinary window now, moved by its title bar like any other (see The Panel as a Window), and the gesture is gone.
The helper binary (SMCWriter) is a minimal executable with no AppKit/SwiftUI dependencies. Its installation at /Library/PrivilegedHelperTools/az-ampere-smc is root-owned, and the complete path must prevent writes or replacement by ordinary users. The watchdog always starts from this checked installation path.
A Keep Awake session adds a group to the menu bar item: its symbol and, for a timed session, the time left. The group is drawn into the icon image to the left of the battery, because a menu bar item keeps its right edge when its width changes: the battery and the percent beside it stay where they are when a session starts or ends and as the countdown loses digits. The symbol leads so the time cannot be read as the battery's. Past the hour the minutes keep two digits ("1h 09m"), so the item changes width at the hour and at ten minutes instead of twice in every hour, and both symbols take the same room (the display badge fills it, the cup sits against its right), so switching Keep Display On changes the symbol and nothing else. The time is drawn in the font of the percent and at the height the button gives its title, read from the button's own layout, so the two share a baseline. One timer redraws the item when the text changes, once a minute; it is armed only while a countdown is on screen.
The display badge is the only part with a color of its own: a rounded rectangle filled with the accent color, as wide as the battery beside it, with the display drawn on it in white. The display is drawn by hand on the pixel grid, not taken from the symbol font, so its outline stays a clean one-pixel line on a display with one pixel per point. The color takes the icon off template rendering the way the update dot and the warning tint do. The parts that stay neutral are then colored by hand, at the strength the system gives a template image and the title: white at 90% on a dark menu bar, black at 85% on a light one, read off the status bar button's own drawing on macOS 27. At full strength the time would come out brighter than the percent next to it.
The panel is where a session is switched on, and the panel hangs from this item. A popover is positioned by a rectangle in its button's coordinates, which start at the button's left edge: the edge that moves. macOS widens a menu bar item in two steps, measured on macOS 27: the button grows in place, and a frame or two later its window moves so that the right edge is back where it was. The popover reads its rectangle again on the first step only, where the old one still names the right spot; after the move the old one names a spot further left, and the next layout of the popover (a row coming or going, which changes the panel's height, is enough) would carry the panel there. So the app sets the rectangle again when the item's window moves, to the same right-hand part of the button the panel was opened from (the battery and the percent, without the group): the panel does not move when the item widens, opens in the same place with or without a session, and follows the icon when a neighboring item pushes it along. Narrowing cannot be kept still this way (on the first step the popover clips its rectangle to the narrower button), so while the panel is attached the item only widens: a shorter countdown, an ended session, the time or the percent switched off leave clear space until the panel closes or is torn off.
The popover takes its size from the panel's view. It used to be told a fixed 580 by 632 points while the view kept itself at its real height, 866 points with every row showing: macOS placed the popover for the smaller height and the panel then grew upwards by the difference. With a display arranged above the menu bar's display, the panel covered the menu bar and reached onto the display above, and a change in the item's width, which makes the popover place itself again, moved it by a few hundred points (measured on such an arrangement). With nothing above the menu bar's display the panel was always seen under the menu bar. It now hangs directly under the menu bar at every height on either arrangement, and a row coming or going resizes it downwards in one step.
The tear-off is NSPopover's own, answered with a window of the app's (detachableWindow(for:)). Left to itself AppKit keeps the popover's window without its arrow: a panel on the menu bar's layer, above every window on screen, with no title bar, which is what the torn-off panel was through 0.0.72. Measured on macOS 27 with real drags: AppKit asks for the window once the drag has gone far enough, goes on moving the popover under the cursor, and when the button comes up shows the window with the top-left corner of its content where the popover's content was (moved back onto the screen where that would leave part of it off), makes it the key window, and closes the popover with the reason detachToWindow. popoverDidDetach is never called on this path, and a drag let go where it began still tears the panel off. AppKit also fades the popover's own window out as it makes the change and leaves it fully transparent: shown again, the popover was in its place, with the keyboard, and could not be seen, so after the panel's window had been closed a click on the menu bar item seemed to open nothing. The app makes that window opaque again right before every show. The window has a view of its own, since AppKit shows the two side by side while one turns into the other, and a fresh one every time it opens; the view goes when the window closes.
A window like any other belongs to an app like any other, so the activation policy follows the window: .regular while it is open, .accessory otherwise (and before anything else at launch, as it always was). macOS does two things on the way that had to be answered. An app that turns regular while it is already active, which it is when the panel has just been dragged, keeps showing the menus of the app in front before it: activating again does nothing, with or without ignoring other apps, and hiding and showing the app works but blinks the window. What works is letting the Dock have the keyboard for a moment and taking it back on the notification that it is gone; the menu bar was Ampere's about 20 ms later and the window never left the screen. The keyboard is taken back only when the Dock is what is in front at that notification, so a user who has just clicked another app is left there. An app that is not active gets its menus with the activation: at launch the reopened window is shown without activating the app (in the Dock if it was minimized), and the first time the app is made active the outcome is read back from NSWorkspace.menuBarOwningApplication half a second later, the Dock being asked once where the menus are still another app's. In the other direction, an app that turns accessory loses the keyboard to the app that had it before, which would put that app's windows over a settings or registration window still open, so Ampere takes the keyboard back for that window. Neither switch reconfigured a display on a Mac with two external displays and no built-in one.
Having the Dock put in front has a side effect that lasts: from then on macOS also reports the app's own mouse-downs to its monitor for clicks in other apps (measured: activating the Dock is enough, hiding the app does the same, the reports were still coming five seconds later, and no window of another app receives the click). That monitor is what closes the attached panel at a click outside the app, so once the panel had been a window, every click inside the attached panel closed it. The monitor no longer takes the report at its word: it asks which window a mouse-down at that spot goes to, and closes the panel only when that window is not one of Ampere's.
The menu bar is built with AppKit (MainMenu.swift). It used to come from a SwiftUI scene that was never shown and was kept for its menu alone. That menu could not be shaped: it had a View menu with nothing in it, a Help item with no help behind it, and an About item that opened the system's panel. Every window was AppKit's already, so the scene went, and the app runs on AppKit's own loop (main.swift).
Quitting closes every window after the app has been told it is terminating (measured), so a window closed that way still counts as open at the next launch; only closing it while the app keeps running clears that.
An ordinary window is not drawn over the Dock the way the attached panel is, on the menu bar's layer. Sized to the whole panel on a small screen, the window would have its title bar against the menu bar and its last row (Settings…, About, Quit) under the Dock, with nowhere left to move it (874 points against the 956 a 13 inch MacBook has in all at its default scaling). The window's view is therefore told how much room its screen has (the visible height less the title bar, again whenever the window changes screens or the screen changes) and is a scroll view of at most that height, as tall as its rows while they fit.
With the panel now staying open beside the registration window, one more thing had to give way. The registration window, like a sheet over the panel, takes the keyboard back whenever the app becomes active, because an accessory app's windows do not always get it by themselves. Beside an open panel that meant it took the keyboard from the panel 50 ms after every click that brought the app back, in the middle of a dragger's drag if that was the click. It takes it back now only when no window of the app has the keyboard, when it has it already, or when the window it is a sheet over has it.
Writing CHIE = 0x08 triggers a USB-C Power Delivery (PD) renegotiation, which briefly disrupts the display signal on the Thunderbolt/USB-C port. This causes a specific problem in clamshell mode (lid closed with external monitors):
- The CHIE write causes a momentary display disconnect.
- macOS detects "no displays available" and triggers clamshell sleep.
- External monitors go permanently black until the lid is opened.
With the lid open, the internal display keeps the system awake through the brief PD disruption, so external monitors reconnect immediately.
| Approach | Result |
|---|---|
caffeinate -dis (power assertions) |
Assertions don't prevent PD-triggered clamshell sleep |
IOPMAssertionCreateWithName (from root and GUI processes) |
Same — assertions insufficient for hardware-level PD events |
IORegistryEntrySetCFProperty / IOConnectSetCFProperty on IOPMrootDomain |
Permission denied on Apple Silicon (kIOReturnUnsupported) |
Writing CH0R instead of CHIE |
No blackout, but doesn't actually enable discharge |
Signal handlers (SIGTERM/SIGHUP) for cleanup in persistent process |
Swift runtime is not async-signal-safe; cleanup code crashed |
fork() to daemonize the watchdog |
Swift/ObjC runtime is not fork-safe; child process crashed |
pmset -a sleep 0 disablesleep 1 displaysleep 0 before the CHIE write. This disables all system sleep at the OS level, preventing macOS from sleeping during the PD disruption.
Because the -a override stamps all power profiles, the original sleep and displaysleep values are captured per profile (Battery and AC, from pmset -g custom) before the override, and restored per profile (pmset -b / pmset -c) when discharge stops — a user with different battery-vs-AC sleep settings gets both back exactly. If the originals cannot be captured (pmset unreadable, marker unwritable), the discharge refuses to start rather than override sleep with no way to restore it.
The pre-override value of the SleepDisabled bit itself is captured the same way (into saved-sleep-disabled), because the bit is global and shared with other keep-awake tools: restoring it blindly to 0 — what builds before this marker did — cancels e.g. Lidless's hold and puts a lid-closed Mac to sleep out from under it. A saved "1" is honored only if the bit still reads 1 at restore time; a holder that released mid-override (auto-off timer, quit) must not be "restored" into a Mac that can never sleep. On re-entry (a hold re-assert, or a re-arm after restart) an existing marker is kept, except that a saved "1" is corrected to "0" when the bit reads 0 — evidence the external holder is gone.
The saved values live in /Library/Application Support/az-ampere/saved-sleep (plus saved-sleep-display and saved-sleep-disabled). The markers deliberately live outside /tmp: macOS wipes /tmp at boot while pmset -a overrides persist across reboots, so a crash + reboot during discharge would otherwise lose the saved values and leave sleep permanently disabled. With the persistent markers, the next launch's cleanup finds them and restores the original settings. (Single-value markers written by older builds — including to the legacy /tmp location — are still honored; their one value is applied to both profiles, matching what those builds' -a restore did.)
The mid-charge sleep hold (see Sleep and Mid-Charge Protection) saves and restores through the same markers via the hold-sleep / release-sleep-hold helper commands, so every existing restore path — nodischarge, the watchdog, launch cleanup — undoes it too. The hold's override is sleep 0 disablesleep 1 only (no displaysleep 0: there is no CHIE write and no PD renegotiation to protect against, so the display may sleep while the machine charges). All three markers are still saved, because the shared restore always puts back all of them.
A watchdog daemon is always running while the app is active. It is spawned via posix_spawn on launch, re-spawned after discharge stops, and also spawned by the discharge command. The mid-charge sleep hold requires it, as the discharge command does: a launch spawn that failed is retried before the first hold, and until a spawn succeeds the hold waits for the next poll, because the watchdog is the only thing that restores sleep if the app dies mid-hold. Every other charge-control write (inhibit, allow, a macOS charge-limit target) retries a failed spawn first but goes ahead without one, since whatever it sets is restored at the next launch; meanwhile the status line and the menu bar icon warn that a crash would leave it in place until then. The daemon:
- Runs as a detached root process (independent of the app and sudo process chain).
- Polls the app's PID every 2 seconds.
- If the app dies (crash,
kill -9, Ctrl+C, etc.), the watchdog cleans up within seconds:- Clears
CHTE = 0x00(allows charging) - Clears
CHIE = 0x00(stops discharge) - Restores sleep settings via
pmset— only if the save-sleep marker file exists (i.e. discharge or the mid-charge sleep hold had overridden pmset); otherwise leaves the user's sleep settings untouched - Puts the macOS charge limit back to the saved original — only if the
saved-native-limitmarker exists (firmware without CHTE) - Exits after successful recovery; if an SMC or pmset operation fails, retries on the next poll and retains any sleep settings still needing restoration
- Clears
The watchdog must be spawned with posix_spawn (not fork) because the Swift/ObjC runtime is not fork-safe — forked children crash when using Foundation, IOKit, or Objective-C APIs. Similarly, signal handlers (SIGTERM/SIGHUP) cannot be used for cleanup because they can only call async-signal-safe C functions, not Swift/Foundation/IOKit APIs. It is spawned with POSIX_SPAWN_SETSID so it runs in its own session: without that it would share the app's foreground process group, and a terminal Ctrl+C (dev runs via run.sh) would SIGINT the watchdog at the same instant as the app it exists to clean up after. It also starts with every signal at its default action and none blocked (POSIX_SPAWN_SETSIGDEF, POSIX_SPAWN_SETSIGMASK), because ignored and blocked signals are inherited across posix_spawn. The install script runs under the administrator prompt, and the watchdog it starts used to inherit an ignored SIGTERM there: the pkill that retires watchdogs signalled it, reported success, and left it running, so a launch that installed or updated the helper ran with two watchdogs, and both restored when the app exited.
On app launch, CHIE and saved sleep settings are restored before existing watchdogs are retired. CHTE is set to inhibit when auto charge is enabled, the battery is at or above the lower bound (or the BMS reports a full battery for a 100% target), and no valid charge-to-upper or charge-to-full session is being resumed; otherwise CHTE is cleared. A fresh watchdog is then spawned. Normal quit uses a single restore command that restores both SMC keys and sleep before retiring the watchdog. If cleanup fails, the watchdog remains alive to retry after the app exits, and while the app runs it retries the restore every two minutes, with the status line warning meanwhile. A sleep hold of the session's own does not delay that retry: the restore releases the hold along with everything else, and the poll that follows arms it again while the charge still wants it. Until that restore lands the app never releases a hold itself: the leftover may include the discharge key, and sleep re-enabled while it is set is what the helper's restore refuses, so the restore releases the hold once the key is clear. A discharge start the helper refuses part-way is rolled back by the helper itself; should that rollback fail too, the app puts the overrides back with a nodischarge and, if that also fails, hands it to the same retry rather than leaving them for the watchdog at exit. A Revoke whose removal failed at its restore joins that retry as well (see Password Prompts).
Nothing runs when Ampere.app is dragged to the Trash, and Homebrew's uninstall stanza runs during brew upgrade as well, so removing the helper there would cost an administrator prompt on every upgrade and removing preferences there would wipe the settings on every upgrade. That is also why the cask has no zap stanza. Instead the app registers a root launchd job, /Library/LaunchDaemons/com.az-code-lab.ampere.cleanup.plist, that runs the installed helper with uninstall-if-missing:<bundle path> at boot (RunAtLoad) and whenever the bundle path changes (WatchPaths). AssociatedBundleIdentifiers lists the job under Ampere in System Settings > General > Login Items & Extensions.
Registration is the register-daemon:<path> helper command, run over the account's passwordless rule after the launch cleanup and after a re-grant from the UI, whenever the installed plist does not match the running copy's path. Root accepts only a real copy of the app (Contents/Info.plist must carry Ampere's bundle identifier), so an account with helper access cannot make root watch other paths. The app skips registration for a bare debug executable and for a quarantined copy running from macOS's randomized App Translocation mount, whose path would vanish at every quit.
When the job runs it looks for the bundle every five seconds and counts two minutes from when it first sees it missing (any sighting ends the run), then uninstalls only if the bundle's parent directory exists (an unmounted volume proves nothing) and no process named Ampere is running from anywhere on disk. Where each running copy's executable is, as the kernel names it (proc_pidpath), tells a move from a removal: a copy whose executable still exists outside a Trash folder was moved, not removed, so the job leaves everything in place and the copy re-registers the job with its new path on relaunch; a copy whose executable was deleted from under it (rm -rf, an uninstaller that skips the quit) or now sits in a Trash folder is on its way out, so the job waits, looking again every two minutes, and uninstalls once that copy has quit and the bundle has stayed missing for a further two minutes. Quitting changes no watched path, so without the wait the helper would have stayed until the next boot. A copy the kernel cannot place keeps everything installed. The grace period is what keeps brew upgrade, brew reinstall, and the in-app updater from triggering it: all three remove and re-create the bundle within seconds.
The helper's uninstall command, used by Revoke once no account remains, runs restore first and stops there if it fails (exit 2), keeping the helper, the saved settings, and the watchdog. Otherwise it removes the sudoers file, the helper, the pre-0.0.60 helper, the state directory, and the job's plist, then unloads the job. purge, which the job runs and which is the manual complete removal, additionally removes each local account's preferences, caches, HTTP storage, and saved window state (accounts from uid 500 up, as the directory service lists them); Revoke never does, because the app stays installed. For a logged-in account the preferences are cleared through that user's cfprefsd first (launchctl asuser <uid> sudo -n -u <user> defaults delete com.az-code-lab.ampere), then the file is unlinked. Deleting the plist alone would not work: the running cfprefsd keeps the domain in memory and rewrites the file, so a reinstall would read the old registration back. Accounts that are not logged in have no cfprefsd to reach, so the direct unlink is enough. Run as the job, the helper hands the unload to a detached shell and exits first, since unloading a job terminates its process.
The app cannot write to the SMC directly — it requires root privileges. Instead, it spawns short-lived root processes (sudo SMCWriter) for each SMC operation, plus a long-lived watchdog daemon as a safety net that cleans up if the app dies unexpectedly, and a launchd job that uninstalls the helper once the app itself is gone.
Ampere (GUI, user)
|
|-- sudo SMCWriter inhibit (one-shot, root)
| |-- SMC write CHTE = 0x01 pause charging
| \-- exit(0)
|
|-- sudo SMCWriter allow (one-shot, root)
| |-- SMC write CHTE = 0x00 allow charging
| \-- exit(0)
|
|-- sudo SMCWriter discharge:<app-pid> (one-shot, root)
| |-- pmset -a sleep 0 disablesleep 1 disable sleep (clamshell fix)
| |-- SMC write CHIE = 0x08 enable active discharge
| |-- posix_spawn SMCWriter watchdog spawn safety net daemon
| \-- exit(0)
|
|-- sudo SMCWriter nodischarge (one-shot, root)
| |-- SMC write CHIE = 0x00 disable active discharge
| |-- pmset restore sleep settings only if save-sleep file exists
| |-- pkill watchdog only after successful restore
| \-- exit(0) failure returns nonzero
|
|-- sudo SMCWriter restore (quit / revoke / migration)
| |-- SMC write CHIE = 0x00 disable active discharge
| |-- SMC write CHTE = 0x00 allow charging
| |-- pmset restore sleep settings only after CHIE clears
| |-- pkill watchdog only after all restores succeed
| \-- exit(0) failure preserves recovery
|
|-- sudo SMCWriter hold-sleep (one-shot, root)
| |-- save pmset markers same markers as discharge
| |-- pmset -a sleep 0 disablesleep 1 keep Mac awake mid-charge
| \-- exit(0) (displaysleep untouched)
|
|-- sudo SMCWriter release-sleep-hold (one-shot, root)
| |-- pmset restore sleep settings only if save-sleep file exists
| \-- exit(0)
|
|-- sudo SMCWriter spawn-watchdog:<pid> (one-shot, root)
| |-- posix_spawn SMCWriter watchdog spawn safety net daemon
| \-- exit(0)
|
|-- sudo SMCWriter register-daemon:<app> (one-shot, root)
| |-- write LaunchDaemons plist watch the installed bundle
| |-- launchctl bootstrap load the cleanup job
| \-- exit(0)
|
|-- sudo SMCWriter uninstall | purge (revoke / manual)
| |-- restore as above; failure removes nothing
| |-- rm sudoers, helper, state dir and the cleanup job's plist
| |-- purge: clear each account's prefs via cfprefsd (logged-in),
| | then rm prefs, caches, HTTP storage, saved state
| |-- launchctl bootout unload the cleanup job
| \-- exit(0)
|
\-- SMCWriter watchdog:<app-pid> (daemon, root, detached)
|-- sleep(2) loop poll every 2 seconds
|-- if app PID gone:
| |-- SMC write CHIE = 0x00 stop discharge
| |-- SMC write CHTE = 0x00 allow charging
| |-- pmset restore sleep only if save-sleep file exists
| \-- exit(0) retry on failure
\-- (runs until app dies)
launchd (root)
\-- SMCWriter uninstall-if-missing:<app> (cleanup job: at boot, on bundle change)
|-- sleep(120) grace period for upgrades
|-- if bundle gone, parent present, a running copy was only moved
| and no Ampere process running:
| \-- purge as above
\-- exit(0)
MIT