Materva 🧉

Keep your MacBook awake with the lid closed — without cooking it.

A tiny macOS menu bar app for people who close the laptop and keep working: long builds, LLM/agent sessions, syncs, downloads. It holds the machine awake in clamshell mode with no external display attached, and — the part other keep-awake tools don't do — it actually turns the internal panel off and cools the machine down while the lid is shut.

Single Swift file plus a few shell scripts. No dependencies, no daemon, no telemetry.

---

The problem this exists to solve

Every tool that keeps a Mac awake with the lid closed does it by disabling clamshell sleep (pmset disablesleep 1). What almost nobody notices is what that leaves behind:

With sleep disabled, closing the lid does not turn the internal display off.

Verified on a MacBook Pro (M5 Pro, macOS 26) by reading powerd's own event log across a real lid close — pmset -g log emits a Display is turned off notification every time the panel actually powers down, and across the whole closed-lid window there was no such event, while the log was demonstrably still recording. Nothing is left to turn the panel off: the system can't sleep (you disabled it on purpose) and the idle display timer keeps getting deferred by display assertions from ordinary running apps — a browser holding NoDisplaySleepAssertion, powerd's own delayDisplayOff.

So the panel stays lit, at whatever brightness you left it, inside a closed laptop, for as long as the mode is on. In a bag, that's watts of heat with nowhere to go.

Careful: the obvious instruments lie about this. AppleARMBacklight's brightness / rawBrightness / BrightnessMicroAmps and IOMobileFramebufferShim's CurrentPowerState all report the brightness setpoint, not whether the panel has power. During a verified 2m42s window with the display genuinely off, every one of them read identically to display-on. Only powerd's notifications are trustworthy here.

What it does

Click the 🧉 in the menu bar to keep the Mac awake (indefinitely, or for 1/2/4/8 hours). While that's on, closing the lid:

1. Turns the internal display off — pmset displaysleepnow, which powers the panel down rather than merely dimming it. Dimming leaves the framebuffer live and the backlight at its floor; this doesn't.
2. Moves your hot processes to efficiency cores — every process you own above 5% CPU gets PRIO_DARWIN_BG via taskpolicy -b. Selection is by measured CPU and uid, not by a hardcoded app list, so it catches whatever is actually hot. Children inherit the policy, so a build started while the lid is shut is throttled too.
3. Lowers Energy Mode — sets Low Power, after saving whatever your AC and Battery profiles were actually set to (they can differ).

Opening the lid reverts all three. Your exact Energy Mode comes back, per profile.

Install

Requires macOS 13+ on Apple Silicon.

git clone https://github.com/luifapaez/materva.git
cd materva
./build.sh                       # swiftc → /Applications/Materva.app, ad-hoc signed
mkdir -p ~/.local/bin && cp scripts/*.sh ~/.local/bin/ && chmod +x ~/.local/bin/*.sh
open /Applications/Materva.app

To launch at login: System Settings → General → Login Items.

One-time setup: passwordless pmset

Read this before running it — it changes your sudo configuration.

The scripts call sudo pmset. For one-click toggling from a menu bar app, that needs a NOPASSWD sudoers rule. It is scoped to /usr/bin/pmset and nothing else, and the command below validates the file with visudo -cf before installing it, so a typo can't lock you out of sudo:

sudo sh -c 'echo "$(whoami) ALL=(ALL) NOPASSWD: /usr/bin/pmset" > /tmp/pmset-sudoers && visudo -cf /tmp/pmset-sudoers && install -m 440 /tmp/pmset-sudoers /etc/sudoers.d/pmset-nopasswd && rm /tmp/pmset-sudoers'

Granting passwordless sudo to any binary widens what a process running as you can do without prompting. pmset only manipulates power management settings, so the blast radius is small — but it is not zero, and you should decide that deliberately rather than paste it because a README said so. To undo: sudo rm /etc/sudoers.d/pmset-nopasswd.

Measured results

One lid cycle, unplugged, on the machine described above:

Materva log:  01:51:33  lid: CLOSED
powerd log:   01:51:33  Display is turned off      <- the panel really powers down
powerd log:   01:52:26  Display is turned on
Materva log:  01:52:27  lid: OPENED

System power draw fell from 9.97–12.54 W (lid open, load-dependent) to 2.90 W (lid closed).

Read that number with its caveats, which are real:

• The battery gauge is heavily filtered and only updated every ~45–60s, so these are settled plateaus, not a curve.
• An 8.00 W plateau appeared 14 seconds before the lid closed, so part of the fall is ordinary load variation, not the tool.
• The figure bundles display-off and CPU throttling; this test does not isolate them.
• Only the display-off half is independently proven, by powerd's log. The throttle's contribution to the wattage is not separately measured.

What it does not fix: the physics of a closed laptop in a bag. With no airflow the machine will still thermally throttle. This reduces the heat generated; it does not improve how heat escapes.

How it stays out of your way

The failure mode that matters for a tool like this isn't "the feature didn't run" — it's "the feature changed something of mine and didn't put it back". The design is built around that:

• Your Energy Mode is never guessed. AC and Battery are captured independently. If the value can't be parsed, the step is skipped for that cycle and logged, rather than restoring you to an invented default later with full confidence.
• The saved value survives a power loss. It lives in ~/Library/Application Support/Materva/, not /tmp — /tmp is wiped at boot, and the battery dying with the lid closed is exactly the scenario that would otherwise destroy the only record of your setting. A file left behind by a crash or a dead battery is consumed automatically on the next launch.
• Throttled PIDs go in /tmp on purpose. PIDs are meaningless after a reboot, so that state should die with the machine.
• A close and an open can never overlap. A mkdir-based mutex at /tmp/materva-lid.lock is shared by both scripts; without it, an open action could delete the PID record while a close action was still writing it, stranding processes on efficiency cores with nothing left that knows they're there. A lock left by a dead process is reclaimed safely.
• Three independent cleanup paths: opening the lid, quitting Materva, and running sleepmode-off.sh. Manual escape hatch: ~/.local/bin/lidclose-off.sh, which is idempotent — running it when nothing is throttled does nothing.

Design and scripts

The shell scripts in ~/.local/bin are the runtime source of truth; the app only executes them. Edit a script and the app inherits the behavior — no rebuild.

Script	Role
sleepmode-on.sh / sleepmode-off.sh	Enter/leave awake mode (pmset disablesleep, caffeinate)
lidclose-on.sh / lidclose-off.sh	The lid-close action and its revert

Lid state is read from AppleClamshellState on IOPMrootDomain via IOKit, polled every 2s and edge-triggered, only while awake mode is on.

Longer write-ups, including the measurement that motivated the whole thing and the mistakes made along the way, live in docs/superpowers/specs/ and DESIGN.md.

Tests

bash tests/test-lidclose.sh            # throttle/restore cycle + the sleepmode-off safety net
bash tests/test-lidlock.sh             # mutex: stale-lock reclaim, pid-less lock, contention
bash tests/test-powermode-roundtrip.sh # Energy Mode capture/restore, incl. parse-failure behavior

MATERVA_SKIP_DISPLAY=1, MATERVA_SKIP_POWERMODE=1 and MATERVA_SKIP_PMSET=1 let the suite run with the lid open without blanking your screen or touching your real settings.

Known issue: the suite uses the production pidfile/lock/save paths, so don't run it while a real closed-lid session is in flight. Parameterizing those paths is the next fix — see the follow-up note in the spec.

How this differs from the alternatives

Amphetamine, KeepingYouAwake, Lungo and plain caffeinate all keep a Mac awake, and several do it well. If that's all you need, use one of those — they're mature and this isn't trying to replace them.

Materva exists for the narrower case: you keep the lid closed, with no external display, while real work runs, and the machine gets hot. That's where the display-still-on finding bites and where the throttling matters.

Limitations

• Apple Silicon, macOS 13+. Not tested on Intel.
• Timers live in the app: quit Materva before a timer fires and the mode stays on until you turn it off. The icon still reflects the truth.
• Fan control is not possible on Apple Silicon without kernel extensions, so it isn't attempted.
• On battery, the Mac stays awake but still drains. With FileVault on, a dead battery drops you to the login screen and the session is gone. Run plugged in for anything long.

License

MIT — see LICENSE.